pygeai 0.1.6__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/gam/clients.py

@@ -0,0 +1,178 @@
+
+from pygeai import logger
+from pygeai.core.base.clients import BaseClient
+from pygeai.core.common.exceptions import MissingRequirementException, InvalidAPIResponseException
+from pygeai.core.utils.validators import validate_status_code
+from pygeai.core.utils.parsers import parse_json_response
+from pygeai.gam.endpoints import GET_ACCESS_TOKEN_V2, GET_USER_INFO_V2, IDP_SIGNIN_V1
+
+
+class GAMClient(BaseClient):
+
+    def generate_signing_url(
+            self,
+            client_id: str = None,
+            redirect_uri: str = None,
+            scope: str = "gam_user_data",
+            state: str = None,
+            response_type: str = "code"
+    ):
+        """
+        Generates the URL for the GAM OAuth 2.0 signin endpoint to initiate user authentication.
+        This method does not perform the signin itself but provides the URL for redirection in a browser-based flow.
+
+        :param client_id: str - Client ID of the application. Required.
+        :param redirect_uri: str - Callback URL configured in the application. Required.
+        :param scope: str - Scope of the user account to access (e.g., "gam_user_data").
+            Defaults to "gam_user_data".
+        :param state: str - Random string to store the status before the request. Required.
+        :param response_type: str - Response type for the signin request. Defaults to "code".
+        :return: str - The URL to redirect to for user authentication in a browser.
+        :raises MissingRequirementException: If required parameters are missing.
+        """
+        if not all([client_id, redirect_uri, state]):
+            raise MissingRequirementException("client_id, redirect_uri, and state are required.")
+
+        params = {
+            "response_type": response_type,
+            "client_id": client_id,
+            "redirect_uri": redirect_uri,
+            "state": state
+        }
+        if scope:
+            params["scope"] = scope
+
+        endpoint = f"{self.api_service.base_url}{IDP_SIGNIN_V1}"
+        redirect_url = f"{endpoint}?{'&'.join(f'{k}={v}' for k, v in params.items())}"
+        return redirect_url
+
+    def get_access_token(
+            self,
+            client_id: str = None,
+            client_secret: str = None,
+            grant_type: str = "password",
+            authentication_type_name: str = "local",
+            scope: str = "gam_user_data",
+            username: str = None,
+            password: str = None,
+            initial_properties: dict = None,
+            repository: str = None,
+            request_token_type: str = "OAuth"
+    ):
+        """
+        Retrieves an access token by sending a POST request to the GAM OAuth 2.0 access token endpoint.
+
+        :param client_id: str - Application Client ID. Required.
+        :param client_secret: str - Application Client Secret. Required.
+        :param grant_type: str - Grant type for authentication. Must be "password". Defaults to "password".
+        :param authentication_type_name: str - Authentication type name. Defaults to "local".
+        :param scope: str - Scope of the user account to access (e.g., "gam_user_data+gam_user_roles").
+            Defaults to "gam_user_data".
+        :param username: str - Username of the user to be authenticated. Required.
+        :param password: str - Password of the user to be authenticated. Required.
+        :param initial_properties: dict - User custom properties array (e.g., [{"Id":"Company","Value":"GeneXus"}]). Optional.
+        :param repository: str - Repository identifier, used only if IDP is multitenant. Optional.
+        :param request_token_type: str - Determines the token type to return and security policy.
+            Options are "OAuth" or "Web". Defaults to "OAuth".
+        :return: dict or str - Access token response containing access_token, token_type, expires_in,
+            refresh_token, scope, and user_guid; returns raw text if JSON parsing fails.
+        """
+        data = {
+            "grant_type": grant_type,
+            "authentication_type_name": authentication_type_name,
+            "scope": scope,
+            "request_token_type": request_token_type
+        }
+        if client_id is not None:
+            data["client_id"] = client_id
+        if client_secret is not None:
+            data["client_secret"] = client_secret
+        if username is not None:
+            data["username"] = username
+        if password is not None:
+            data["password"] = password
+        if initial_properties is not None:
+            data["initial_properties"] = initial_properties
+        if repository is not None:
+            data["repository"] = repository
+
+        headers = {
+            "Content-Type": "application/x-www-form-urlencoded"
+        }
+        response = self.api_service.post(
+            endpoint=GET_ACCESS_TOKEN_V2,
+            data=data,
+            headers=headers,
+            form=True
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "get access token")
+
+    def get_user_info(
+            self,
+            access_token: str
+    ):
+        """
+        Retrieves user information by sending a GET request to the GAM OAuth 2.0 userinfo endpoint.
+
+        :param access_token: str - Access token obtained from the access_token endpoint. Required.
+        :return: dict or str - User information response containing guid, username, email, and other user
+            details based on requested scopes; returns raw text if JSON parsing fails.
+        """
+        headers = {
+            "Authorization": access_token,
+            "Content-Type": "application/x-www-form-urlencoded"
+        }
+        response = self.api_service.get(
+            endpoint=GET_USER_INFO_V2,
+            headers=headers
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "get user info")
+
+    def refresh_access_token(
+            self,
+            client_id: str = None,
+            client_secret: str = None,
+            grant_type: str = "refresh_token",
+            refresh_token: str = None
+    ):
+        """
+        Refreshes an access token by sending a GET request to the GAM OAuth 2.0 access token endpoint.
+
+        :param client_id: str - Application Client ID. Required.
+        :param client_secret: str - Application Client Secret. Required.
+        :param grant_type: str - Grant type for authentication. Must be "refresh_token". Defaults to "refresh_token".
+        :param refresh_token: str - Refresh token obtained from a previous access token response. Required.
+        :return: dict or str - New access token response containing access_token, token_type, expires_in,
+            refresh_token, scope, and user_guid; returns raw text if JSON parsing fails.
+        """
+        data = {
+            "grant_type": grant_type,
+        }
+        if client_id is not None:
+            data["client_id"] = client_id
+        if client_secret is not None:
+            data["client_secret"] = client_secret
+        if refresh_token is not None:
+            data["refresh_token"] = refresh_token
+
+        headers = {
+            "Content-Type": "application/x-www-form-urlencoded"
+        }
+        response = self.api_service.post(
+            endpoint=GET_ACCESS_TOKEN_V2,
+            data=data,
+            headers=headers,
+            form=True
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "refresh access token")
+
+    def get_authentication_types(self):
+        response = self.api_service.get(
+            endpoint=GET_ACCESS_TOKEN_V2,
+            params={},
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "get authentication types")

pygeai/gam/endpoints.py

@@ -0,0 +1,4 @@
+GET_ACCESS_TOKEN_V2 = "oauth/gam/v2.0/access_token"     # POST -> Sends the user credentials to get a new Token
+GET_USER_INFO_V2 = "oauth/gam/v2.0/userinfo"            # GET -> Send the access_token obtained in the previous request and get the user info depending on the scopes you have indicated.
+GET_AUTHENTICATION_TYPES_V1 = "v1/gam/authentication-types"     # GET -> Get authentication types
+IDP_SIGNIN_V1 = "/oauth/gam/signin"     # NO METHOD -> Just generates URL for authentication in browser

pygeai/health/clients.py

@@ -0,0 +1,24 @@
+
+from pygeai import logger
+from pygeai.core.base.clients import BaseClient
+from pygeai.core.common.exceptions import InvalidAPIResponseException
+from pygeai.core.utils.validators import validate_status_code
+from pygeai.core.utils.parsers import parse_json_response
+from pygeai.health.endpoints import STATUS_CHECK_V1
+
+
+class HealthClient(BaseClient):
+
+    def check_api_status(self) -> dict:
+        """
+        Checks the status of the API.
+
+        :return: dict - The API response as a JSON object containing details about the API status.
+        If the response cannot be parsed as JSON, returns the raw response text.
+        """
+        endpoint = STATUS_CHECK_V1
+        response = self.api_service.get(
+            endpoint=endpoint
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "check API status")

pygeai/health/endpoints.py

@@ -0,0 +1 @@
+STATUS_CHECK_V1 = "/v1/system/status"   # GET -> Health Check SAIA APIs

pygeai/lab/agents/clients.py

@@ -0,0 +1,426 @@
+from typing import Optional, List, Dict
+
+from pygeai import logger
+from pygeai.core.common.exceptions import MissingRequirementException, InvalidAPIResponseException
+from pygeai.core.utils.validators import validate_status_code
+from pygeai.core.utils.parsers import parse_json_response
+from pygeai.lab.agents.endpoints import CREATE_AGENT_V2, LIST_AGENTS_V2, GET_AGENT_V2, CREATE_SHARING_LINK_V2, \
+    PUBLISH_AGENT_REVISION_V2, DELETE_AGENT_V2, UPDATE_AGENT_V2, UPSERT_AGENT_V2, EXPORT_AGENT_V2, IMPORT_AGENT_V2
+from pygeai.lab.constants import VALID_ACCESS_SCOPES
+from pygeai.lab.clients import AILabClient
+
+
+class AgentClient(AILabClient):
+
+    def list_agents(
+            self,
+            status: str = "",
+            start: int = "",
+            count: int = "",
+            access_scope: str = "public",
+            allow_drafts: bool = True,
+            allow_external: bool = False
+    ) -> dict:
+        """
+        Retrieves a list of agents associated with the specified project.
+
+        :param status: str, optional - Filter agents by status (e.g., "active", "draft"). Defaults to "" (no filtering).
+        :param start: int, optional - Starting index for pagination. Defaults to "" (no offset).
+        :param count: int, optional - Maximum number of agents to retrieve. Defaults to "" (no limit).
+        :param access_scope: str, optional - Filter agents by access scope ("public" or "private"). Defaults to "public".
+        :param allow_drafts: bool, optional - Include draft agents in the results. Defaults to True.
+        :param allow_external: bool, optional - Include external agents in the results. Defaults to False.
+        :return: dict - JSON response containing the list of agents.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        """
+        endpoint = LIST_AGENTS_V2
+        headers = {
+            "Authorization": self.api_service.token,
+            "ProjectId": self.project_id
+        }
+
+        logger.debug(f"Listing agents for project with ID {self.project_id}")
+
+        response = self.api_service.get(
+            endpoint=endpoint,
+            headers=headers,
+            params={
+                "status": status,
+                "start": start,
+                "count": count,
+                "accessScope": access_scope,
+                "allowDrafts": allow_drafts,
+                "allowExternal": allow_external
+            }
+        )
+        validate_status_code(response)
+        return parse_json_response(response, f"list agents for project {self.project_id}")
+
+    def create_agent(
+            self,
+            name: str,
+            access_scope: str,
+            public_name: str,
+            job_description: str,
+            avatar_image: str,
+            description: str,
+            agent_data_prompt: dict,
+            agent_data_llm_config: dict,
+            agent_data_strategy_name: str,
+            agent_data_models: list,
+            agent_data_resource_pools: Optional[List[Dict]] = None,
+            automatic_publish: bool = False
+    ) -> dict:
+        """
+        Creates a new agent in the specified project.
+
+        :param name: str - Name of the agent (must be unique within the project, non-empty, and exclude ':' or '/').
+        :param access_scope: str - Access scope of the agent ("public" or "private").
+        :param public_name: str - Public name for the agent, required if access_scope is "public" (must follow domain/library convention, e.g., 'com.example.my-agent').
+        :param job_description: str - Description of the agent's role (optional).
+        :param avatar_image: str - URL for the agent's avatar image (optional).
+        :param description: str - Detailed description of the agent’s purpose (optional).
+        :param agent_data_prompt: dict - Prompt configuration, including 'context', 'instructions', and optional 'examples' (e.g., {'context': str, 'instructions': str, 'examples': [{'inputData': str, 'output': str}]}).
+        :param agent_data_llm_config: dict - LLM configuration (e.g., {'maxTokens': int, 'timeout': int, 'sampling': {'temperature': float}}).
+        :param agent_data_strategy_name: str - Strategy name to be used.
+        :param agent_data_models: list - List of models the agent can use (e.g., [{'name': 'gpt-4o', 'llmConfig': dict}]).
+        :param agent_data_resource_pools: Optional[List[Dict]] - Resource pools for tools and helper agents (e.g., [{'name': str, 'tools': [{'name': str, 'revision': int}], 'agents': [{'name': str, 'revision': int}]}]).
+        :param automatic_publish: bool - Automatically publish the agent after creation (default: False).
+        :return: dict - JSON response containing the created agent details.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        :raises ValueError: If access_scope is invalid.
+        """
+        if access_scope is not None and access_scope not in VALID_ACCESS_SCOPES:
+            raise ValueError(f"Access scope must be one of {', '.join(VALID_ACCESS_SCOPES)}.")
+
+        data = {
+            "agentDefinition": {
+                "name": name,
+                "accessScope": access_scope,
+                "publicName": public_name,
+                "jobDescription": job_description,
+                "avatarImage": avatar_image,
+                "description": description,
+            }
+        }
+        if (
+                agent_data_prompt or agent_data_strategy_name or agent_data_prompt or agent_data_resource_pools or
+                agent_data_llm_config or agent_data_models
+        ):
+            data["agentDefinition"]["agentData"] = {}
+        if agent_data_resource_pools is not None:
+            data["agentDefinition"]["agentData"]["resourcePools"] = agent_data_resource_pools
+        if agent_data_prompt is not None:
+            data["agentDefinition"]["agentData"]["prompt"] = agent_data_prompt
+        if agent_data_llm_config is not None:
+            data["agentDefinition"]["agentData"]["llmConfig"] = agent_data_llm_config
+        if agent_data_strategy_name is not None:
+            data["agentDefinition"]["agentData"]["strategyName"] = agent_data_strategy_name
+        if agent_data_models is not None:
+            data["agentDefinition"]["agentData"]["models"] = agent_data_models
+        logger.debug(f"Creating agent with data: {data}")
+
+        endpoint = CREATE_AGENT_V2
+        if automatic_publish:
+            endpoint = f"{endpoint}?automaticPublish=true"
+
+        headers = {
+            "Authorization": self.api_service.token,
+            "ProjectId": self.project_id
+        }
+
+        response = self.api_service.post(
+            endpoint=endpoint,
+            headers=headers,
+            data=data
+        )
+
+        validate_status_code(response)
+        return parse_json_response(response, f"create agent for project {self.project_id}")
+
+
+    def get_agent(
+            self,
+            agent_id: str,
+            revision: str = 0,
+            version: int = 0,
+            allow_drafts: bool = True
+    ) -> dict:
+        """
+        Retrieves details of a specific agent from the specified project.
+
+        :param agent_id: str - Unique identifier of the agent to retrieve.
+        :param revision: str, optional - Specific revision of the agent to retrieve (default: 0, latest revision).
+        :param version: int, optional - Specific version of the agent to retrieve (default: 0, latest version).
+        :param allow_drafts: bool, optional - Include draft agents in the results (default: True).
+        :return: dict - JSON response containing the agent details.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        :raises MissingRequirementException: If project_id or agent_id is not provided.
+        """
+        if not agent_id:
+            raise MissingRequirementException("agent_id must be specified in order to retrieve the agent")
+
+        endpoint = GET_AGENT_V2.format(agentId=agent_id)
+        headers = {
+            "Authorization": self.api_service.token,
+            "ProjectId": self.project_id
+        }
+
+        logger.debug(f"Retrieving agent detail with ID {agent_id}")
+
+        response = self.api_service.get(
+            endpoint=endpoint,
+            headers=headers,
+            params={
+                "revision": revision,
+                "version": version,
+                "allowDrafts": allow_drafts,
+            }
+        )
+        validate_status_code(response)
+        return parse_json_response(response, f"retrieve agent {agent_id} for project {self.project_id}")
+
+
+    def create_sharing_link(
+            self,
+            agent_id: str,
+    ) -> dict:
+        """
+        Creates a sharing link for a specific agent in the specified project.
+
+        :param agent_id: str - Unique identifier of the agent for which to create a sharing link.
+        :return: dict - JSON response containing the sharing link details.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        :raises MissingRequirementException: If project_id or agent_id is not provided.
+        """
+        if not agent_id:
+            raise MissingRequirementException("agent_id must be specified in order to create sharing link")
+
+        endpoint = CREATE_SHARING_LINK_V2.format(agentId=agent_id)
+        headers = {
+            "Authorization": self.api_service.token,
+            "ProjectId": self.project_id
+        }
+
+        logger.debug(f"Creating sharing link for agent with ID {agent_id}")
+
+        response = self.api_service.get(
+            endpoint=endpoint,
+            headers=headers,
+            params={}
+        )
+        validate_status_code(response)
+        return parse_json_response(response, f"create sharing link for agent {agent_id} in project {self.project_id}")
+
+
+    def publish_agent_revision(
+            self,
+            agent_id: str,
+            revision: str
+    ) -> dict:
+        """
+        Publishes a specific revision of an agent in the specified project.
+
+        :param agent_id: str - Unique identifier of the agent to publish.
+        :param revision: str - Revision of the agent to publish.
+        :return: dict - JSON response containing the result of the publish operation.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        """
+        endpoint = PUBLISH_AGENT_REVISION_V2.format(agentId=agent_id)
+        headers = {
+            "Authorization": self.api_service.token,
+            "ProjectId": self.project_id
+        }
+
+        logger.debug(f"Publishing revision {revision} for agent with ID {agent_id}")
+
+        response = self.api_service.post(
+            endpoint=endpoint,
+            headers=headers,
+            data={
+                "revision": revision,
+            }
+        )
+        validate_status_code(response)
+        return parse_json_response(response, f"publish revision {revision} for agent {agent_id} in project {self.project_id}")
+
+
+    def delete_agent(
+            self,
+            agent_id: str,
+    ) -> dict:
+        """
+        Deletes a specific agent from the specified project.
+
+        :param agent_id: str - Unique identifier of the agent to delete.
+        :return: dict - JSON response confirming the deletion.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        """
+        endpoint = DELETE_AGENT_V2.format(agentId=agent_id)
+        headers = {
+            "Authorization": self.api_service.token,
+            "ProjectId": self.project_id
+        }
+
+        logger.debug(f"Deleting agent with ID {agent_id}")
+
+        response = self.api_service.delete(
+            endpoint=endpoint,
+            headers=headers,
+            data={}
+        )
+        if response.status_code != 204:
+            logger.error(f"Unable to delete agent {agent_id} from project {self.project_id}: JSON parsing error (status {response.status_code}). Response: {response.text}")
+            raise InvalidAPIResponseException(f"Unable to delete agent {agent_id} from project {self.project_id}: {response.text}")
+        else:
+            return {}
+
+    def update_agent(
+            self,
+            agent_id: str,
+            name: str,
+            access_scope: str,
+            public_name: str,
+            job_description: str,
+            avatar_image: str,
+            description: str,
+            agent_data_prompt: dict,
+            agent_data_llm_config: dict,
+            agent_data_strategy_name: dict,
+            agent_data_models: list,
+            agent_data_resource_pools: Optional[List[Dict]] = None,
+            automatic_publish: bool = False,
+            upsert: bool = False
+    ) -> dict:
+        """
+        Updates an existing agent in the specified project or upserts it if specified.
+
+        :param agent_id: str - Unique identifier of the agent to update (required for updates).
+        :param name: str - Updated name of the agent (must be unique, non-empty, exclude ':' or '/'; optional).
+        :param access_scope: str - Updated access scope ("public" or "private").
+        :param public_name: str - Updated public name, required if access_scope is "public" (must follow domain/library convention).
+        :param job_description: str - Updated role description (optional).
+        :param avatar_image: str - Updated avatar image URL (optional).
+        :param description: str - Updated purpose description (optional).
+        :param agent_data_prompt: dict - Updated prompt configuration (e.g., {'context': str, 'instructions': str, 'examples': [{'inputData': str, 'output': str}]}).
+        :param agent_data_llm_config: dict - Updated LLM configuration (e.g., {'maxTokens': int, 'timeout': int, 'sampling': {'temperature': float}}).
+        :param agent_data_strategy_name: str - Updated StrategyName configuration.
+        :param agent_data_models: list - Updated model list (e.g., [{'name': 'gpt-4o', 'llmConfig': dict}]).
+        :param agent_data_resource_pools: Optional[List[Dict]] - Updated resource pools (e.g., [{'name': str, 'tools': [{'name': str, 'revision': int}], 'agents': [{'name': str, 'revision': int}]}]).
+        :param automatic_publish: bool - Automatically publish the agent after updating (default: False).
+        :param upsert: bool - Create the agent if it does not exist (default: False).
+        :return: dict - JSON response containing the updated or created agent details.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        :raises ValueError: If access_scope is invalid.
+        """
+        if access_scope is not None and access_scope not in VALID_ACCESS_SCOPES:
+            raise ValueError(f"Access scope must be one of {', '.join(VALID_ACCESS_SCOPES)}.")
+
+        data = {
+            "agentDefinition": {
+                "name": name,
+                "accessScope": access_scope,
+                "publicName": public_name,
+                "jobDescription": job_description,
+                "avatarImage": avatar_image,
+                "description": description,
+            }
+        }
+        if (
+                agent_data_prompt or agent_data_strategy_name or agent_data_prompt or agent_data_resource_pools or
+                agent_data_llm_config or agent_data_models
+        ):
+            data["agentDefinition"]["agentData"] = {}
+        if agent_data_resource_pools is not None:
+            data["agentDefinition"]["agentData"]["resourcePools"] = agent_data_resource_pools
+        if agent_data_prompt is not None:
+            data["agentDefinition"]["agentData"]["prompt"] = agent_data_prompt
+        if agent_data_llm_config is not None:
+            data["agentDefinition"]["agentData"]["llmConfig"] = agent_data_llm_config
+        if agent_data_strategy_name is not None:
+            data["agentDefinition"]["agentData"]["strategyName"] = agent_data_strategy_name
+        if agent_data_models is not None:
+            data["agentDefinition"]["agentData"]["models"] = agent_data_models
+
+        logger.debug(f"Updating agent with ID {agent_id} with data: {data}")
+
+        endpoint = UPSERT_AGENT_V2 if upsert else UPDATE_AGENT_V2
+        endpoint = endpoint.format(agentId=agent_id) if agent_id else endpoint.format(agentId=name)
+
+        if automatic_publish:
+            endpoint = f"{endpoint}?automaticPublish=true"
+
+        headers = {
+            "Authorization": self.api_service.token,
+            "ProjectId": self.project_id
+        }
+
+        response = self.api_service.put(
+            endpoint=endpoint,
+            headers=headers,
+            data=data
+        )
+
+        validate_status_code(response)
+        return parse_json_response(response, f"update agent {agent_id} in project {self.project_id}")
+
+
+    def export_agent(
+            self,
+            agent_id: str,
+    ) -> dict:
+        """
+        Retrieves details of a specific agent from the specified project.
+
+        :param agent_id: str - Unique identifier of the agent to retrieve.
+        :return: dict - JSON response containing the agent details.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        :raises MissingRequirementException: If project_id or agent_id is not provided.
+        """
+        if not agent_id:
+            raise MissingRequirementException("agent_id must be specified in order to export the agent")
+
+        endpoint = EXPORT_AGENT_V2.format(agentId=agent_id)
+        headers = {
+            "Authorization": self.api_service.token,
+            "ProjectId": self.project_id
+        }
+
+        logger.debug(f"Exporting agent with ID {agent_id}")
+
+        response = self.api_service.get(
+            endpoint=endpoint,
+            headers=headers,
+        )
+        validate_status_code(response)
+        return parse_json_response(response, f"export agent {agent_id} for project {self.project_id}")
+
+    def import_agent(
+            self,
+            data: dict,
+    ) -> dict:
+        """
+        Retrieves details of a specific agent from the specified project.
+
+        :param data: dict - Agent specification to import
+        :return: dict - JSON response containing the agent details.
+        :raises InvalidAPIResponseException: If the response cannot be parsed as JSON or an error occurs.
+        :raises MissingRequirementException: If project_id or agent_id is not provided.
+        """
+        if not data:
+            raise MissingRequirementException("data for spec must be specified in order to import the agent")
+
+        endpoint = IMPORT_AGENT_V2
+        headers = {
+            "Authorization": self.api_service.token,
+            "ProjectId": self.project_id
+        }
+
+        response = self.api_service.post(
+            endpoint=endpoint,
+            headers=headers,
+            data=data
+        )
+        validate_status_code(response)
+        return parse_json_response(response, f"import agent for project {self.project_id}")
+

pygeai/lab/agents/endpoints.py

@@ -0,0 +1,12 @@
+CREATE_AGENT_V2 = "v2/agents"  # POST -> Create agent
+LIST_AGENTS_V2 = "v2/agents"  # GET -> List agents
+GET_AGENT_V2 = "v2/agents/{agentId}"  # GET -> Get agent data
+CREATE_SHARING_LINK_V2 = "v2/agents/{agentId}/sharing-token"  # GET -> Create sharing link
+PUBLISH_AGENT_REVISION_V2 = "v2/agents/{agentId}/publish-revision"  # POST -> Publish Agent revision
+DELETE_AGENT_V2 = "v2/agents/{agentId}"  # DEL -> Delete agent
+UPDATE_AGENT_V2 = "v2/agents/{agentId}"  # PUT -> Update agent
+UPSERT_AGENT_V2 = "v2/agents/{agentId}/upsert"  # PUT -> Update or Insert agent
+EXPORT_AGENT_V2 = "v2/agents/{agentId}/export"  # GET -> Export agent
+IMPORT_AGENT_V2 = "v2/agents/import"  # POST -> Import agent
+# EXPORT_AGENT_V4 = "v4/agents/{agentId}/export"  # GET -> Export agent
+# IMPORT_AGENT_V4 = "v4/agents/import"  # POST -> Import agent