Agent Management
================

The Agent module provides functionality to create, manage, and interact with AI agents in the Globant Enterprise AI Lab. Agents are autonomous AI entities configured with specific prompts, LLM settings, reasoning strategies, and can be integrated into agentic processes.

This section covers:

* Creating agents
* Retrieving agent information
* Updating agent configuration
* Listing agents
* Publishing agent revisions
* Deleting agents

For each operation, you have three implementation options:

* `Command Line`_
* `Low-Level Service Layer`_ (using clients)
* `High-Level Service Layer`_ (using managers)


Create Agent
~~~~~~~~~~~~

Creates a new agent with specified configuration including prompt instructions, inputs, outputs, examples, LLM configuration, and reasoning strategy.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab agent create \
      --name "Translator Agent" \
      --job-description "Translates text between languages" \
      --description "Agent that translates from any language to English" \
      --access-scope private

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.agents.clients import AgentClient
    
    client = AgentClient()
    
    agent_data = {
        "name": "Translator Agent",
        "status": "active",
        "accessScope": "private",
        "jobDescription": "Translates text between languages",
        "description": "Agent that translates from any language to English",
        "isDraft": False,
        "isReadonly": False,
        "agentData": {
            "prompt": {
                "instructions": "Translate the provided text to English",
                "inputs": ["text", "target_language"],
                "outputs": [
                    {"key": "translated_text", "description": "The translated text"},
                    {"key": "summary", "description": "Summary of the translation"}
                ]
            },
            "strategyName": "Dynamic Prompting",
            "llmConfig": {
                "maxTokens": 5000,
                "timeout": 0,
                "sampling": {"temperature": 0.5, "topK": 0, "topP": 0}
            },
            "models": [{"name": "gpt-4-turbo-preview"}]
        }
    }
    
    response = client.create_agent(agent_data=agent_data, automatic_publish=False)
    print(response)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    from pygeai.lab.models import Agent, AgentData, Prompt, LlmConfig, Model, Sampling, PromptOutput, PromptExample
    
    manager = AILabManager()
    
    agent = Agent(
        status="active",
        name="Translator Agent",
        access_scope="private",
        job_description="Translates text between languages",
        description="Agent that translates from any language to English",
        is_draft=False,
        is_readonly=False,
        agent_data=AgentData(
            prompt=Prompt(
                instructions="Translate the provided text to English",
                inputs=["text", "target_language"],
                outputs=[
                    PromptOutput(key="translated_text", description="The translated text"),
                    PromptOutput(key="summary", description="Summary of the translation")
                ],
                examples=[
                    PromptExample(
                        input_data="hello world [es]",
                        output='{"translated_text":"Hello world","summary":"greeting"}'
                    )
                ]
            ),
            strategy_name="Dynamic Prompting",
            llm_config=LlmConfig(
                max_tokens=5000,
                timeout=0,
                sampling=Sampling(temperature=0.5, top_k=0, top_p=0)
            ),
            models=[Model(name="gpt-4-turbo-preview")]
        )
    )
    
    result = manager.create_agent(agent=agent, automatic_publish=False)
    print(f"Created agent: {result.name}, ID: {result.id}")


Get Agent
~~~~~~~~~

Retrieves detailed information about a specific agent by its ID or name.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab agent get --id "agent-uuid"

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.agents.clients import AgentClient
    
    client = AgentClient()
    
    agent_data = client.get_agent(agent_id="agent-uuid")
    print(agent_data)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    
    manager = AILabManager()
    
    agent = manager.get_agent(id_or_name="agent-uuid")
    print(f"Agent: {agent.name}")
    print(f"Description: {agent.description}")
    print(f"Status: {agent.status}")


List Agents
~~~~~~~~~~~

Retrieves a list of agents with optional filtering.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab agent list --start 0 --count 10

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.agents.clients import AgentClient
    
    client = AgentClient()
    
    agents_list = client.list_agents(start="0", count="10")
    print(agents_list)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    from pygeai.lab.models import FilterSettings
    
    manager = AILabManager()
    
    filter_settings = FilterSettings(start="0", count="10")
    agents = manager.list_agents(filter_settings=filter_settings)
    
    print(f"Found {len(agents.agents)} agents:")
    for agent in agents.agents:
        print(f"  - {agent.name} (ID: {agent.id})")


Update Agent
~~~~~~~~~~~~

Updates an existing agent's configuration.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab agent update \
      --id "agent-uuid" \
      --name "Updated Translator Agent" \
      --description "Enhanced translation agent"

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.agents.clients import AgentClient
    
    client = AgentClient()
    
    updated_data = {
        "name": "Updated Translator Agent",
        "description": "Enhanced translation agent",
        "agentData": {
            "llmConfig": {
                "maxTokens": 8000,
                "sampling": {"temperature": 0.7}
            }
        }
    }
    
    response = client.update_agent(
        agent_id="agent-uuid",
        agent_data=updated_data,
        automatic_publish=False
    )
    print(response)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    from pygeai.lab.models import Agent, AgentData, LlmConfig, Sampling
    
    manager = AILabManager()
    
    # First, get the existing agent
    existing_agent = manager.get_agent(id_or_name="agent-uuid")
    
    # Update fields
    existing_agent.name = "Updated Translator Agent"
    existing_agent.description = "Enhanced translation agent"
    existing_agent.agent_data.llm_config.max_tokens = 8000
    existing_agent.agent_data.llm_config.sampling.temperature = 0.7
    
    result = manager.update_agent(
        id_or_name="agent-uuid",
        agent=existing_agent,
        automatic_publish=False
    )
    print(f"Updated agent: {result.name}")


Publish Agent Revision
~~~~~~~~~~~~~~~~~~~~~~~

Publishes a specific revision of an agent, making it available for use.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab agent publish --id "agent-uuid" --revision 2

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.agents.clients import AgentClient
    
    client = AgentClient()
    
    response = client.publish_agent_revision(
        agent_id="agent-uuid",
        revision=2
    )
    print(response)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    
    manager = AILabManager()
    
    result = manager.publish_agent_revision(
        id_or_name="agent-uuid",
        revision=2
    )
    print(f"Published agent revision: {result}")


Delete Agent
~~~~~~~~~~~~

Deletes a specific agent by its ID or name.

Command Line
^^^^^^^^^^^^

.. code-block:: shell

    geai lab agent delete --id "agent-uuid"

Low-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.agents.clients import AgentClient
    
    client = AgentClient()
    
    response = client.delete_agent(agent_id="agent-uuid")
    print(response)

High-Level Service Layer
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from pygeai.lab.managers import AILabManager
    
    manager = AILabManager()
    
    result = manager.delete_agent(id_or_name="agent-uuid")
    print(f"Agent deleted: {result}")
