Aggiungere uno strumento funzione a un agente utilizzando ADK

Questa esercitazione descrive i passi per aggiungere uno strumento di funzione a un agente esistente in Generative AI Agents.

Gli strumenti di funzione consentono all'agente di utilizzare funzioni scritte su misura e definite localmente come strumenti. Sono molto flessibili e particolarmente utili per i casi aziendali grazie all'elaborazione locale, alla facile autenticazione e alla perfetta integrazione con le funzionalità esistenti.

In questo esempio, abbiamo un agente meteorologico dotato di uno strumento di funzione personalizzato. Questo è anche noto come agente chiamante funzione.

Nota

Gli strumenti di funzione vengono eseguiti localmente sul tuo lato.

Ciò che viene inviato a un agente remoto sui server OCI è la definizione della funzione (nome della funzione, parametri della funzione e relative descrizioni). I server OCI non accedono all'implementazione delle funzioni.

Panoramica

Quando viene eseguita una query meteo, l'agente remoto esegue effettivamente la classificazione dell'intento per utilizzare lo strumento get_weather. Ad esempio, in base alla query in linguaggio naturale Is it cold in Seattle?, l'agente remoto riempie lo slot dell'argomento e effettua la richiesta.

L'agente invia una richiesta contenente le azioni richieste per l'applicazione client. In questo caso, l'azione richiesta per il client è quella di richiamare lo strumento di funzione get_weather con un argomento location=Seattle.

Agent Development Kit (ADK) esegue le operazioni riportate di seguito.

analizza l'azione richiesta
trova la funzione locale registrata
esegue questa funzione con argomenti specifici
cattura l'output della chiamata di funzione
invia di nuovo l'output all'agente remoto, in modo che l'agente possa utilizzare tale output per generare una risposta al prompt utente

Diagramma

Requisiti indispensabili

Prima di creare un'applicazione agente, effettuare le operazioni riportate di seguito.

Sul computer su cui è in esecuzione il codice, impostare un file di configurazione API OCI. Assicurarsi che la configurazione si riferisca a un'area in cui sono ospitati gli agenti AI generativa.
Creare un ambiente virtuale:
```
python3 -m venv <myenv>
```
Attivare l'ambiente virtuale.
```
source <myenv>/bin/activate
```
Installare l'ADK. Python ADK richiede Python 3.10 o versioni successive.
```
pip install "oci[adk]
```

Impostare un compartimento per lo sviluppo

Per impostare il compartimento, effettuare le operazioni riportate di seguito.

Chiedere a un amministratore di aggiungere il criterio IAM seguente:
```
allow <a-group-your-user-name-belongs-to> to manage all-resources in compartment <your-compartment-name>
```
Importante

Fornire l'accesso completo a un compartimento è conveniente per un'esercitazione. Tuttavia, in produzione, utilizzare criteri più restrittivi per limitare l'accesso all'agente. Vedere Accesso agli agenti AI generativa.
Accedi alla console di Oracle Cloud Infrastructure.
Aprire il menu di navigazione e selezionare Identità e sicurezza. In Identità, selezionare Compartimenti.
Selezionare Crea compartimento.
Compilare le seguenti informazioni:
- Nome: <your-compartment-name>
- Descrizione: Compartment for <your-description>.
- Compartimento padre: <your-tenancy>(root)
Selezionare Crea compartimento.

Riferimento: creare un compartimento

Crea agente

Nella barra di navigazione della console, selezionare la stessa area selezionata per il file di configurazione nella sezione precedente.
Nella pagina elenco Agenti, selezionare Crea agente. Per assistenza nella ricerca della pagina elenco, vedere Elenca agenti.
Immettere le informazioni riportate di seguito.
- Nome: <your-agent-name>
- Compartimento: selezionare un compartimento nel quale si è autorizzati a lavorare.
- Descrizione: agente senza strumenti iniziali. Aggiunta di strumenti con ADK.
- Messaggio di benvenuto: lasciare vuoto.
- Istruzioni di instradamento: lasciare vuoto.
Selezionare Successivo per passare al passo Aggiungi strumento. Salta questa pagina e non aggiungi strumenti.
Selezionare Next.
(Facoltativo) Selezionare Crea automaticamente un endpoint per questo agente per creare un endpoint quando l'agente viene creato e mantenere tutte le altre opzioni predefinite.
Selezionare Avanti e quindi Crea agente.

Nota

Accettare le condizioni di licenza se richiesto.
Attendere che l'agente diventi attivo.

Raccogli informazioni necessarie

Nell'ambiente in uso, copiare l'area impostata per il file di configurazione in un blocco note. Ad esempio, us-chicago-1.
Nella console, nella pagina elenco Agenti, selezionare l'agente creato in questa esercitazione. Per assistenza nella ricerca della pagina elenco, vedere Elenca agenti.
Copiare l'OCID per l'agente e incollarlo in un blocco note per la sezione successiva.

OCID agente di esempio: ocid1.genaiagent.oc1.us-chicago-1.<unique-id>
Selezionare l'endpoint per l'agente.
Copiare l'OCID per l'endpoint e incollarlo in un blocco note per la sezione successiva.

OCID endpoint di esempio: ocid1.genaiagentendpoint.oc1.us-chicago-1.<unique-id>
Passare a Identità e sicurezza e selezionare Compartimenti. Selezionare il compartimento con l'agente. Copiare l'OCID per il compartimento e incollarlo in un blocco note.

OCID compartimento di esempio: ocid1.compartment.oc1..<unique-id>

Creare un file locale

Dal terminale, vai alla tua home directory.
Creare una directory denominata ADK.
Spostarsi nella directory ADK.
Creare un file denominato weather_agent.py.

Incollare il codice seguente in weather-agent.py.

Sostituire <region-where-agent-is-created> e <your-agent-endpoint> con i valori raccolti.

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()

Aggiungi lo strumento

Importante

Se si sceglie un agente esistente invece di crearne uno nuovo per questa esercitazione, prima di eseguire questo file assicurarsi che l'agente remoto non disponga di strumenti. Questo programma elimina tutti gli strumenti sull'agente remoto, a meno che non si tratti dello strumento denominato get_weather. Se trova uno strumento get_weather remoto, aggiorna lo strumento remoto da sincronizzare con quello locale.

Nella console andare alla pagina dei dettagli dell'agente e prendere nota dei valori relativi.
- Istruzioni di instradamento: deve essere vuoto.
- Selezionare Strumenti. L'elenco degli strumenti deve essere vuoto.
Eseguire il file Python, get_weather
```
python3 weather-agent.py
```

Nell'output, rivedere i nomi delle funzioni locali e remote e assicurarsi che lo strumento get_weather venga aggiunto all'agente remoto. Output di esempio:

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.

Nella console andare alla pagina dei dettagli dell'agente e guardare gli aggiornamenti.
- Nella pagina dei dettagli dell'agente, le istruzioni di instradamento cambiano da vuota a Perform weather queries using the given tools.
- Selezionare Strumenti. Lo strumento, get_weather, viene visualizzato nell'elenco degli strumenti.
- Selezionare get_weather e, in Richieste di lavoro, verificare che l'operazione CREATE_TOOL sia riuscita.

Leggi gli output

Nell'output leggere il messaggio dell'utente. Output di esempio:


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

Leggi la risposta della chat. Output di esempio:


╭────────────────── 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\"}"              │
│         }                                                           │
│     }                                                               │
│ ]                                                                   │
╰─────────────────────────────────────────────────────────────────────╯

Leggi la chiamata di funzione richiesta dall'agente. Output di esempio:


╭─ 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                                                          │
╰──────────────────────────────────────────────────────────────────────╯

Leggi il risultato dell'esecuzione della funzione. Output di esempio:


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

Leggere la richiesta di chat nell'output di esempio dell'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                                                          │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯

Leggere la risposta della chat dall'output di esempio dell'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                                                                                           │
╰────────────────────────────────────────────────────────────────────────────────────────────────╯

Leggi la risposta di esecuzione dell'agente in linguaggio naturale. Output di esempio:


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

Rimuovi lo strumento

Nell'ambiente locale creare un file denominato list_agent_tools.py con il contenuto seguente. Inoltre, aggiornare tutte le variabili ID con le informazioni sull'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()

Questo script chiama l'operazione find_tool del client e restituisce tutti gli strumenti per un agente specificato in un compartimento specificato.

Controllare l'output:

[
    {
    "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>

Creare un file denominato delete_tools.py e copiare le seguenti informazioni per utilizzare l'operazione delete_tool per eliminare il file weather_tool. Inoltre, aggiornare tutte le variabili ID con le informazioni sull'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()

Nella console, andare alla pagina dei dettagli dell'agente e vedere che lo strumento viene eliminato.
Disattivare l'ambiente virtuale.
decativate

Documentazione dell'infrastruttura Oracle Cloud