Adición de una herramienta de función a un agente mediante ADK

En este tutorial se tratan los pasos para agregar una herramienta de función a un agente existente en agentes de IA generativa.

Las herramientas de función permiten al agente utilizar funciones personalizadas definidas localmente como herramientas. Son muy flexibles y particularmente útiles para casos empresariales debido a su procesamiento local, su fácil autenticación y su integración perfecta con la funcionalidad existente.

En este ejemplo, tenemos un agente meteorológico equipado con una herramienta de función personalizada. Esto también se conoce como agente de llamada de función.

Nota

Las herramientas de función se ejecutan localmente de su lado.

Lo que se envía a un agente remoto en los servidores de OCI es la definición de función (nombre de función, parámetros de función y sus descripciones). Los servidores OCI no acceden a la implantación de funciones.

Descripción general

Cuando se realiza una consulta meteorológica, el agente remoto realiza efectivamente la clasificación de intenciones para utilizar la herramienta get_weather. Por ejemplo, según la consulta de lenguaje natural Is it cold in Seattle?, el agente remoto rellena el espacio de argumento y realiza la solicitud.

El agente envía una solicitud que contiene las acciones necesarias para la aplicación cliente. En este caso, la acción necesaria para el cliente es llamar a la herramienta de función get_weather con un argumento location=Seattle.

El kit de desarrollo de agentes (ADK) realiza lo siguiente:

analiza la acción necesaria
encuentra la función local registrada
ejecuta esta función con los argumentos específicos
captura la salida de llamada de función
devuelve la salida al agente remoto, de modo que el agente pueda utilizar esa salida para generar una respuesta a la petición de datos del usuario

Diagrama

Requisitos

Antes de crear una aplicación de agente, realice estos pasos:

En la máquina en la que se ejecuta el código, configure un archivo de configuración de API de OCI. Asegúrese de que la configuración hace referencia a una región en la que se alojan los agentes de IA generativa.

Cree un entorno virtual:

python3 -m venv <myenv>

Active el entorno virtual.

source <myenv>/bin/activate

Instale el ADK. El ADK de Python requiere Python 3.10 o posterior.
```
pip install "oci[adk]
```

Configuración de un compartimento para desarrollo

Para configurar el compartimento, siga estos pasos:

Solicite a un administrador que agregue la siguiente política de IAM:
```
allow <a-group-your-user-name-belongs-to> to manage all-resources in compartment <your-compartment-name>
```
Importante

Proporcionar acceso completo a un compartimento es conveniente para un tutorial. Sin embargo, en producción, utilice políticas más restrictivas para limitar el acceso al agente. Consulte Obtención de acceso a agentes de IA generativa.
Conéctese a la consola de Oracle Cloud Infrastructure.
Abra el menú de navegación y seleccione Identity & Security. En Identidad, seleccione Compartimentos.
Seleccione Create Compartment.
Rellene la siguiente información:
- Nombre: <your-compartment-name>
- Descripción: Compartment for <your-description>.
- Compartimento de principal: <your-tenancy>(root)
Seleccione Create compartment.

Referencia: Creación de un compartimento

Crear un agente

En la barra de navegación de la consola, seleccione la misma región que seleccionó para el archivo de configuración en la sección anterior.
En la página de lista Agentes, seleccione Crear agente. Si necesita ayuda para encontrar la página de lista, consulte Lista de agentes.
Introduzca la siguiente información:
- Name: <your-agent-name>
- Compartimento: seleccione un compartimento en cuyo compartimento tenga permiso para trabajar.
- Descripción: agente sin herramientas iniciales. Agregar herramientas con ADK.
- Mensaje de bienvenida: déjelo en blanco.
- Instrucciones de enrutamiento: deje en blanco.
Seleccione Siguiente para navegar al paso Agregar herramienta. Omita esta página y no agregue ninguna herramienta.
Seleccione Next (Siguiente).
(Opcional) Seleccione Crear automáticamente un punto final para este agente para crear un punto final cuando se cree el agente y mantener el resto de opciones por defecto.
Seleccione Siguiente y, a continuación, seleccione Crear agente.

Nota

Si se solicita, acepte las condiciones de la licencia.
Espere a que el agente se active.

Recopilar información necesaria

En el entorno, copie la región que haya configurado para el archivo de configuración en un bloc de notas. Por ejemplo, us-chicago-1.
En la consola, en la página de lista Agentes, seleccione el agente que ha creado en este tutorial. Si necesita ayuda para encontrar la página de lista, consulte Lista de agentes.
Copie el OCID del agente y péguelo en un bloc de notas para la siguiente sección.

OCID de agente de ejemplo: ocid1.genaiagent.oc1.us-chicago-1.<unique-id>
Seleccione el punto final para este agente.
Copie el OCID del punto final y péguelo en un bloc de notas para la siguiente sección.

OCID de punto final de ejemplo: ocid1.genaiagentendpoint.oc1.us-chicago-1.<unique-id>
Vaya a Identity and Security y seleccione Compartments. Seleccione el compartimento con el agente. Copie el OCID del compartimento y péguelo en un bloc de notas.

OCID de compartimento de ejemplo: ocid1.compartment.oc1..<unique-id>

Creación de un archivo local

Desde el terminal, vaya al directorio principal.
Cree un directorio denominado ADK.
Cambie al directorio ADK.
Cree un archivo denominado weather_agent.py.

Pegue el siguiente código en weather-agent.py.

Sustituya <region-where-agent-is-created> y <your-agent-endpoint> por los valores que ha recopilado.

from typing import Dict
from adk import Agent, AgentClient, tool

@tool
def get_weather(location: str) -> Dict[str, str]:
    """Get the weather for a given location"""
    return {"location": location, "temperature": 72, "unit": "F"}


def main():
    # Create a client with your authentication details
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region="<region-where-agent-is-created>"
    )

    # Instantiate the agent with your agent endpoint ID and the tool

    agent = Agent(
        client=client,
        agent_endpoint_id="<your-agent-endpoint>",
        instructions="Perform weather queries using the given tools.",
        tools=[get_weather]
    )

    # Set up the agent (configures instructions and tools in the remote agent resource)
    agent.setup()

    # Run the agent with an input
    input = "Is it cold in Seattle?"
    response = agent.run(input)

    # Print the response
    response.pretty_print()

if __name__ == "__main__":
    main()

Cómo agregar la herramienta

Importante

Si ha elegido un agente existente en lugar de crear uno nuevo para este tutorial, antes de ejecutar este archivo, asegúrese de que el agente remoto no tiene herramientas. Este programa suprime todas las herramientas del agente remoto, a menos que sea la herramienta denominada herramienta get_weather. Si encuentra una herramienta get_weather remota, actualiza la herramienta remota para que se sincronice con la local.

En la consola, vaya a la página de detalles del agente y observe los valores para.
- Instrucciones de enrutamiento: debe estar en blanco.
- Seleccione Herramientas. La lista de herramientas debe estar vacía.
Ejecute el archivo Python, get_weather
```
python3 weather-agent.py
```

En la salida, revise los nombres de funciones locales y remotas y asegúrese de que la herramienta get_weather se está agregando al agente remoto. Salida de ejemplo:

Waiting for agent to be active...
╭─ Local and remote function tools found ─╮
│ Local function tools (1):               │
│ ['get_weather']                         │
│                                         │
│ Remote function tools (0):              │
│ []                                      │
╰─────────────────────────────────────────╯
Found local tool not in remote tools: get_weather. Adding it to the remote agent...
Waiting for tool to be active...
Checking synchronization of local and remote RAG tools...                                                             
No active remote RAG tools found. No local RAG tool to add.

En la consola, vaya a la página de detalles del agente y observe las actualizaciones.
- En la página de detalles del agente, las instrucciones de enrutamiento cambian de blanco a Perform weather queries using the given tools.
- Seleccione Herramientas. La herramienta get_weather aparece en la lista de herramientas.
- Seleccione get_weather y, en solicitudes de trabajo, compruebe que la operación CREATE_TOOL se ha realizado correctamente.

Leer las salidas

En la salida, lea el mensaje de usuario. Salida de ejemplo:


                                                      
╭──────────────────────────────────── Chat request to remote agent ─────────────────────────────────────╮
│ (Local --> Remote)                                                                                    │
│                                                                                                       │
│ user message:                                                                                         │
│ Is it cold in Seattle?                                                                                │
│                                                                                                       │
│ performed actions by client:                                                                          │
│ []                                                                                                    │
│                                                                                                       │
│ session id:                                                                                           │
│ ocid1.genaiagentsession.<unique-id>                                                          │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯

Lee la respuesta del chat. Salida de ejemplo:


╭────────────────── Chat response from remote agent ──────────────────╮
│ (Local <-- Remote)                                                  │
│                                                                     │
│ agent message:                                                      │
│ null                                                                │
│                                                                     │
│ required actions for client to take:                                │
│ [                                                                   │
│     {                                                               │
│         "action_id": "<unique-id>",        │
│         "required_action_type": "FUNCTION_CALLING_REQUIRED_ACTION", │
│         "function_call": {                                          │
│             "name": "get_weather",                                  │
│             "arguments": "{\"location\": \"Seattle\"}"              │
│         }                                                           │
│     }                                                               │
│ ]                                                                   │
╰─────────────────────────────────────────────────────────────────────╯

Lee la llamada a la función solicitada por el agente. Salida de ejemplo:


╭─ Function call requested by agent and mapped local handler function ─╮
│ Agent function tool name:                                            │
│ get_weather                                                          │
│                                                                      │
│ Agent function tool call arguments:                                  │
│ {'location': 'Seattle'}                                              │
│                                                                      │
│ Mapped local handler function name:                                  │
│ get_weather                                                          │
╰──────────────────────────────────────────────────────────────────────╯

Lee el resultado de la ejecución de la función. Salida de ejemplo:


╭─────── Obtained local function execution result ────────╮
│ {'location': 'Seattle', 'temperature': 72, 'unit': 'F'} │
╰─────────────────────────────────────────────────────────╯

Lea la solicitud de chat en la salida de ejemplo del agente remoto:


╭──────────────────────────────────── Chat request to remote agent ─────────────────────────────────────╮
│ (Local --> Remote)                                                                                    │
│                                                                                                       │
│ user message:                                                                                         │
│ null                                                                                                  │
│                                                                                                       │
│ performed actions by client:                                                                          │
│ [                                                                                                     │
│     {                                                                                                 │
│         "action_id": "<unique-id>",                                          │
│         "performed_action_type": "FUNCTION_CALLING_PERFORMED_ACTION",                                 │
│         "function_call_output": "{\"location\": \"Seattle\", \"temperature\": 72, \"unit\": \"F\"}"   │
│     }                                                                                                 │
│ ]                                                                                                     │
│                                                                                                       │
│ session id:                                                                                           │
│ ocid1.genaiagentsession.oc1.us-chicago-1.xxx                                                          │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯

Lea la respuesta de chat de la salida de ejemplo del agente remoto:


╭─────────────────────────────── Chat response from remote agent ────────────────────────────────╮
│ (Local <-- Remote)                                                                             │
│                                                                                                │
│ agent message:                                                                                 │
│ {                                                                                              │
│     "role": "AGENT",                                                                           │
│     "content": {                                                                               │
│         "text": "It's not cold in Seattle. The current temperature is 72 degrees Fahrenheit.", │
│         "citations": null,                                                                     │
│         "paragraph_citations": null                                                            │
│     },                                                                                         │
│     "time_created": "2025-04-10T18:47:33.617000+00:00"                                         │
│ }                                                                                              │
│                                                                                                │
│ required actions for client to take:                                                           │
│ null                                                                                           │
╰────────────────────────────────────────────────────────────────────────────────────────────────╯

Lee la respuesta de ejecución del agente que está en lenguaje natural. Salida de ejemplo:


╭──────────────────────────────────────────────── Agent run response ────────────────────────────────────────────────╮
│ agent text message:                                                                                                │
│ It's not cold in Seattle. The current temperature is 72 degrees Fahrenheit.                                        │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Eliminar la herramienta

En el entorno local, cree un archivo denominado list_agent_tools.py con el siguiente contenido. Actualice también todas las variables de ID con la información de OCID.

import json
from adk import AgentClient



def main():

    agent_id = "ocid1.genaiagent.<unique-id>"
    agent_compartment_id = "<your-compartment-ocid>"
    region_id = "<your-region-id>"
    # Enter an OCI region such as "us-chicago-1" or airport code such as "ORD"

    # Create a client with your authentication details
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region=region_id
    )


    # Find the tools of the following agent in the following compartment
    tool_list = client.find_tools(agent_compartment_id, agent_id)

    json_str = json.dumps(tool_list, indent=4)

    

    print(json_str)

    for item in tool_list:
        print(f"Tool Name: {item.get('display_name')}  \nTool OCID: {item.get('id')}")


if __name__ == "__main__":
    main()

Este script llama a la operación find_tool del cliente y devuelve todas las herramientas para un agente especificado en un compartimento especificado.

Revise la salida:

[
    {
    "id": "ocid1.genaiagenttool.<unique-id>",
        "lifecycle_state": "ACTIVE",
        "time_created": "2025-04-10T21:49:19.350000+00:00",
        "time_updated": "2025-04-10T21:49:42.132000+00:00",
        "display_name": "get_weather",
        "description": "Get the weather for a given location created by ADK",
        "compartment_id": "<your-compartment-ocid>",
                                "agent_id": "ocid1.genaiagent.<unique-id>",
        "tool_config": {
            "tool_config_type": "FUNCTION_CALLING_TOOL_CONFIG",
            "function": {
                "name": "get_weather",
                "description": "Get the weather for a given location",
                "parameters": {
                    "type": "object",
                    "properties": "{\"location\": {\"type\": \"string\"}}",
                    "required": "['location']"
                }
            }
        },
        "metadata": null,
        "freeform_tags": {
            "ModifiedBy": "ADK",
            "CreatedBy": "ADK"
        },
        "defined_tags": {
            "Oracle-Tags": {
                "CreatedBy": "john.doe@example.com",
                "CreatedOn": "2025-04-10T21:49:19.277Z"
            }
        },
        "system_tags": {}
    }
]
Tool Name: get_weather  
Tool OCID: ocid1.genaiagenttool.oc1.us-chicago-1.amaa<your-ocid>

Cree un archivo denominado delete_tools.py y copie la siguiente información para utilizar la operación delete_tool para suprimir weather_tool. Actualice también todas las variables de ID con la información de OCID.

import json
from adk import AgentClient



def main():

agent_id = "ocid1.genaiagent.<unique-id>"
    agent_compartment_id = "<your-compartment-ocid>"
    endpoint_id = "ocid1.genaiagentendpoint.<unique-id>"
    region_id = "<your-region-id>"

    # Create a client with your authentication details
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region=region_id
    )


    # Find the tools of the following agent in the following compartment
    tool_list = client.find_tools(agent_compartment_id, agent_id)

    json_str = json.dumps(tool_list, indent=4)

    

    print(json_str)

    for item in tool_list:
        print(f"Tool Name: {item.get('display_name')}  \nTool OCID: {item.get('id')}")

    for item in tool_list:
        print(f"Deleting tool {item.get('display_name')} with tool OCID: {item.get('id')}")
        client.delete_tool(item.get('id'))

    print ("Tool deleted!")

if __name__ == "__main__":
    main()

En la consola, vaya a la página de detalles del agente y compruebe que la herramienta se ha suprimido.
Desactive el entorno virtual.
decativate

Documentación de Oracle Cloud Infrastructure