Einem Agent mit ADK ein Funktionstool hinzufügen

In diesem Tutorial werden die Schritte zum Hinzufügen eines Funktionstools zu einem vorhandenen Agent in Generative AI Agents beschrieben.

Mit Funktionstools kann der Agent benutzerdefinierte, lokal definierte Funktionen als Tools verwenden. Sie sind sehr flexibel und besonders nützlich für Unternehmensfälle aufgrund der lokalen Verarbeitung, der einfachen Authentifizierung und der nahtlosen Integration mit vorhandenen Funktionen.

In diesem Beispiel haben wir einen Wetteragent, der mit einem benutzerdefinierten Funktionstool ausgestattet ist. Dies wird auch als Funktionsaufruf-Agent bezeichnet.

Hinweis

Funktionstools werden lokal auf Ihrer Seite ausgeführt.

Was an einen Remote-Agent auf OCI-Servern gesendet wird, ist die Funktionsdefinition (Funktionsname, Funktionsparameter und deren Beschreibungen). OCI-Server greifen nicht auf die Funktionsimplementierung zu.

Überblick

Wenn eine Wetterabfrage durchgeführt wird, führt der Remote-Agent effektiv die Intent-Klassifizierung aus, um das Tool get_weather zu verwenden. Beispiel: Der Remote-Agent füllt basierend auf der natürlichen Sprachabfrage Is it cold in Seattle? den Argumentslot aus und stellt die Anforderung.

Der Agent sendet eine Anforderung mit den erforderlichen Aktionen für die Clientanwendung. In diesem Fall muss der Client das Funktionstool get_weather mit dem Argument location=Seattle aufrufen.

Das Agent Development Kit (ADK) führt Folgendes aus:

parst die erforderliche Aktion
findet die registrierte lokale Funktion
Führt diese Funktion mit den spezifischen Argumenten aus
erfasst die Ausgabe des Funktionsaufrufs
leitet die Ausgabe an den Remote-Agent zurück, sodass der Agent diese Ausgabe verwenden kann, um eine Antwort auf die Benutzereingabeaufforderung zu generieren

Diagramm

Voraussetzungen

Führen Sie die folgenden Schritte aus, bevor Sie eine Agent-App erstellen:

Richten Sie auf dem Rechner, auf dem Ihr Code ausgeführt wird, eine OCI-API-Konfigurationsdatei ein. Stellen Sie sicher, dass sich die Konfiguration auf eine Region bezieht, in der generative KI-Agents gehostet werden.
Virtuelle Umgebung erstellen:
```
python3 -m venv <myenv>
```
Aktivieren Sie die virtuelle Umgebung.
```
source <myenv>/bin/activate
```
Installieren Sie ADK. Python ADK erfordert Python 3.10 oder höher.
```
pip install "oci[adk]
```

Compartment für Entwicklung einrichten

So richten Sie das Compartment ein:

Bitten Sie einen Administrator, die folgende IAM-Policy für Sie hinzuzufügen:
```
allow <a-group-your-user-name-belongs-to> to manage all-resources in compartment <your-compartment-name>
```
Wichtig

Das Bereitstellen des vollständigen Zugriffs auf ein Compartment ist für ein Tutorial praktisch. Verwenden Sie in der Produktion jedoch restriktivere Policys, um den Zugriff auf den Agent zu begrenzen. Siehe Zugriff auf generative KI-Agents erhalten.
Melden Sie sich bei der Oracle Cloud Infrastructure-Konsole an.
Öffnen Sie das Navigationsmenü, und wählen Sie Identität und Sicherheit aus. Wählen Sie unter Identität die Option Compartments aus.
Wählen Sie Compartment erstellen aus.
Geben Sie die folgenden Informationen ein:
- Name: <your-compartment-name>
- Beschreibung: Compartment for <your-description>.
- Übergeordnetes Compartment: <your-tenancy>(root)
Wählen Sie Compartment erstellen aus.

Referenz: Compartment erstellen

Agent erstellen

Wählen Sie in der Navigationsleiste der Konsole dieselbe Region aus, die Sie im vorherigen Abschnitt für die Konfigurationsdatei ausgewählt haben.
Wählen Sie auf der Listenseite Agents die Option Agent erstellen aus. Wenn Sie Hilfe beim Suchen der Listenseite benötigen, finden Sie weitere Informationen unter Agents auflisten.
Geben Sie folgende Informationen ein:
- Name: <your-agent-name>
- Compartment: Wählen Sie ein Compartment aus, für das Sie die erforderliche Berechtigung haben.
- Beschreibung: Agent ohne anfängliche Tools. Tools mit ADK hinzufügen.
- Willkommensmeldung: Lassen Sie dieses Feld leer.
- Routinganweisungen: Lassen Sie dieses Feld leer.
Wählen Sie Weiter, um zum Schritt Tool hinzufügen zu navigieren. Überspringen Sie diese Seite, und fügen Sie keine Tools hinzu.
Wählen Sie Weiter.
(Optional) Wählen Sie Endpunkt für diesen Agent automatisch erstellen aus, um beim Erstellen des Agent einen Endpunkt zu erstellen, und behalten Sie alle anderen Standardoptionen bei.
Wählen Sie Weiter, Agent erstellen aus.

Hinweis

Akzeptieren Sie die Lizenzbedingungen auf Anforderung.
Warten Sie, bis der Agent aktiv wird.

Erforderliche Informationen erfassen

Kopieren Sie in Ihrer Umgebung die Region, die Sie für die Konfigurationsdatei eingerichtet haben, in einem Notizblock. Beispiel: us-chicago-1.
Wählen Sie in der Konsole auf der Listenseite Agents den Agent aus, den Sie in diesem Tutorial erstellt haben. Wenn Sie Hilfe beim Suchen der Listenseite benötigen, finden Sie weitere Informationen unter Agents auflisten.
Kopieren Sie die OCID für den Agent, und fügen Sie sie in ein Notizbuch für den nächsten Abschnitt ein.

Beispiel-Agent-OCID: ocid1.genaiagent.oc1.us-chicago-1.<unique-id>
Wählen Sie den Endpunkt für diesen Agent aus.
Kopieren Sie die OCID für den Endpunkt, und fügen Sie sie in ein Notizbuch für den nächsten Abschnitt ein.

Beispiel-Endpunkt-OCID: ocid1.genaiagentendpoint.oc1.us-chicago-1.<unique-id>
Navigieren Sie zu "Identität und Sicherheit", und wählen Sie Compartments aus. Wählen Sie das Compartment mit dem Agent aus. Kopieren Sie die OCID für das Compartment, und fügen Sie sie in ein Notizbuch ein.

Beispiel-Compartment-OCID: ocid1.compartment.oc1..<unique-id>

Lokale Datei erstellen

Wechseln Sie vom Terminal zu Ihrem Home-Verzeichnis.
Erstellen Sie ein Verzeichnis namens ADK.
Wechseln Sie in das ADK-Verzeichnis.
Erstellen Sie eine Datei namens weather_agent.py.

Fügen Sie den folgenden Code in weather-agent.py ein.

Ersetzen Sie <region-where-agent-is-created> und <your-agent-endpoint> durch die erfassten Werte.

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

Tool hinzufügen

Wichtig

Wenn Sie einen vorhandenen Agent ausgewählt haben, anstatt einen neuen für dieses Tutorial zu erstellen, stellen Sie vor dem Ausführen dieser Datei sicher, dass der Remote-Agent keine Tools enthält. Dieses Programm löscht alle Tools auf dem Remote-Agent, es sei denn, es handelt sich um das Tool namens get_weather. Wenn ein Remote-Tool get_weather gefunden wird, wird das Remote-Tool aktualisiert, das mit dem lokalen synchronisiert werden soll.

Navigieren Sie in der Konsole zur Detailseite des Agent, und notieren Sie sich die Werte für.
- Routinganweisungen: Muss leer sein.
- Wählen Sie Extras. Die Toolliste sollte leer sein.
Führen Sie die Python-Datei get_weather aus
```
python3 weather-agent.py
```

Prüfen Sie in der Ausgabe die lokalen und Remote-Funktionsnamen, und stellen Sie sicher, dass das Tool get_weather dem Remote-Agent hinzugefügt wird. Beispielausgabe:

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.

Navigieren Sie in der Konsole zur Detailseite des Agent, und beobachten Sie die Updates.
- Auf der Agent-Detailseite werden die Routinganweisungen von leer in Perform weather queries using the given tools. geändert.
- Wählen Sie Extras. Das Tool get_weather wird in der Liste der Tools angezeigt.
- Wählen Sie get_weather aus, und prüfen Sie unter Arbeitsanforderungen, ob der Vorgang CREATE_TOOL erfolgreich war.

Ausgabe lesen

Lesen Sie in der Ausgabe die Benutzernachricht. Beispielausgabe:


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

Lesen Sie die Chatantwort. Beispielausgabe:


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

Lesen Sie den vom Agent angeforderten Funktionsaufruf. Beispielausgabe:


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

Lesen Sie das Ergebnis der Funktionsausführung. Beispielausgabe:


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

Lesen Sie die Chatanfrage an die Beispielausgabe des Remote-Agents:


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

Lesen Sie die Chatantwort aus der Beispielausgabe des Remote-Agents:


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

Lesen Sie die Agent-Ausführungsantwort in natürlicher Sprache. Beispielausgabe:


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

Tool entfernen

Erstellen Sie in Ihrer lokalen Umgebung eine Datei namens list_agent_tools.py mit dem folgenden Inhalt. Aktualisieren Sie außerdem alle ID-Variablen mit Ihren OCID-Informationen.

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

Dieses Skript ruft den Vorgang find_tool des Clients auf und gibt alle Tools für einen angegebenen Agent in einem angegebenen Compartment zurück.

Prüfen Sie die Ausgabe:

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

Erstellen Sie eine Datei mit dem Namen delete_tools.py, und kopieren Sie die folgenden Informationen, um den Vorgang delete_tool zum Löschen von weather_tool zu verwenden. Aktualisieren Sie außerdem alle ID-Variablen mit Ihren OCID-Informationen.

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

Gehen Sie in der Konsole zur Detailseite des Agent, und prüfen Sie, ob das Tool gelöscht wurde.
Deaktivieren Sie die virtuelle Umgebung.
decativate

Oracle Cloud Infrastructure-Dokumentation