Ajouter un outil de fonction à un agent à l'aide de ADK

Ce tutoriel décrit les étapes à suivre pour ajouter un outil de fonction à un agent existant dans les agents d'IA générative.

Les outils de fonction permettent à l'agent d'utiliser des fonctions personnalisées, définies localement, en tant qu'outils. Ils sont très flexibles et particulièrement utiles pour les affaires d'entreprise en raison de leur traitement local, de leur authentification facile et de leur intégration transparente aux fonctionnalités existantes.

Dans cet exemple, nous avons un agent météorologique équipé d'un outil de fonction personnalisé. Il s'agit également d'un agent appelant une fonction.

Note

Les outils de fonction sont exécutés localement de votre côté.

Ce qui est envoyé à un agent distant sur les serveurs OCI est la définition de la fonction (nom de la fonction, paramètres de la fonction et leurs descriptions). Les serveurs OCI n'accèdent pas à la mise en oeuvre de la fonction.

Aperçu

Lorsqu'une interrogation météorologique est effectuée, l'agent distant effectue efficacement la classification d'intention pour utiliser l'outil get_weather. Par exemple, sur la base de l'interrogation en langage naturel Is it cold in Seattle?, l'agent distant remplit l'emplacement des arguments et effectue la demande.

L'agent envoie une demande qui contient les actions requises pour l'application client. Dans ce cas, l'action requise pour le client est d'appeler l'outil de fonction get_weather avec un argument location=Seattle.

La trousse de développement d'agent (ADK) effectue les opérations suivantes :

Analyse l'action requise
recherche la fonction locale enregistrée
exécute cette fonction avec les arguments spécifiques
capture la sortie d'appel de fonction
soumet la sortie à l'agent distant, de sorte que l'agent puisse utiliser cette sortie pour générer une réponse à l'invite utilisateur

Diagramme

Préalables

Avant de créer une application d'agent, procédez comme suit :

Sur l'ordinateur exécutant votre code, configurez un fichier de configuration d'API OCI. Assurez-vous que la configuration fait référence à une région dans laquelle les agents d'IA générative sont hébergés.
Créez un environnement virtuel :
```
python3 -m venv <myenv>
```
Activez l'environnement virtuel.
```
source <myenv>/bin/activate
```
Installez ADK. Python ADK nécessite Python 3.10 ou une version ultérieure.
```
pip install "oci[adk]
```

Configurer un compartiment à développer

Pour configurer le compartiment, procédez comme suit :

Demandez à un administrateur d'ajouter la politique IAM suivante pour vous :
```
allow <a-group-your-user-name-belongs-to> to manage all-resources in compartment <your-compartment-name>
```
Important

Il est pratique de fournir un accès complet à un compartiment pour un tutoriel. Toutefois, en production, utilisez des politiques plus restrictives pour limiter l'accès à l'agent. Voir Accès aux agents d'IA générative.
Connectez-vous à la console Oracle Cloud Infrastructure.
Ouvrez le menu de navigation et sélectionnez Identité et sécurité. Sous Identité, sélectionnez Compartiments.
Sélectionnez Créer un compartiment.
Entrez les informations suivantes :
- Nom : <your-compartment-name>
- Description : Compartment for <your-description>.
- compartiment parent : <your-tenancy>(root)
Sélectionnez Créer un compartiment.

Inférence : Créez un compartiment

Créer un agent

Dans la barre de navigation de la console, sélectionnez la même région que celle que vous avez sélectionnée pour le fichier de configuration dans la section précédente.
Dans la page de liste Agents, sélectionnez Créer un agent. Si vous avez besoin d'aide pour trouver la page de liste, voir Liste des agents.
Entrez les informations suivantes :
- Nom : <your-agent-name>
- Compartiment : Sélectionnez un compartiment que vous êtes autorisé à utiliser.
- Description : Agent sans outils initiaux. Ajout d'outils avec ADK.
- Message de bienvenue : laissez ce champ vide.
- Instructions d'acheminement : Laissez ce champ vide.
Sélectionnez Suivant pour naviguer jusqu'à l'étape Ajouter un outil. Ignorez cette page et n'ajoutez aucun outil.
Sélectionnez Suivant.
(Facultatif) Sélectionnez Créer automatiquement un point d'extrémité pour cet agent pour créer un point d'extrémité lorsque l'agent est créé et conserver toutes les autres options par défaut.
Sélectionnez Suivant, puis Créer un agent.

Note

Acceptez les conditions de licence si nécessaire.
Attendez que l'agent devienne actif.

Collecter les informations requises

Dans votre environnement, copiez la région que vous avez configurée pour le fichier de configuration dans un bloc-notes. Par exemple, us-chicago-1.
Dans la console, dans la page de liste Agents, sélectionnez l'agent que vous avez créé dans ce tutoriel. Si vous avez besoin d'aide pour trouver la page de liste, voir Liste des agents.
Copiez l'OCID de l'agent et collez-le dans un bloc-notes pour la section suivante.

Exemple d'OCID d'agent : ocid1.genaiagent.oc1.us-chicago-1.<unique-id>
Sélectionnez le point d'extrémité de cet agent.
Copiez l'OCID du point d'extrémité et collez-le dans un bloc-notes pour la section suivante.

Exemple d'OCID de point d'extrémité : ocid1.genaiagentendpoint.oc1.us-chicago-1.<unique-id>
Naviguez jusqu'à Identité et sécurité et sélectionnez Compartiments. Sélectionnez le compartiment avec l'agent. Copiez l'OCID du compartiment et collez-le dans un bloc-notes.

Exemple d'OCID de compartiment : ocid1.compartment.oc1..<unique-id>

Créer un fichier local

Depuis le terminal, accédez à votre répertoire d'origine.
Créez un répertoire nommé ADK.
Accédez au répertoire ADK.
Créez un fichier nommé weather_agent.py.

Collez le code suivant dans weather-agent.py.

Remplacez <region-where-agent-is-created> et <your-agent-endpoint> par les valeurs que vous avez collectées.

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

Ajouter l'outil

Important

Si vous avez choisi un agent existant au lieu d'en créer un nouveau pour ce tutoriel, avant d'exécuter ce fichier, assurez-vous que l'agent distant ne dispose d'aucun outil. Ce programme supprime tous les outils de l'agent distant, sauf s'il s'agit de l'outil nommé get_weather. S'il trouve un outil get_weather distant, il met à jour l'outil distant pour qu'il soit synchronisé avec l'outil local.

Dans la console, naviguez jusqu'à la page de détails de l'agent et notez les valeurs pour.
- Instructions de gamme d'opérations : Doit être vide.
- Sélectionnez Outils. La liste d'outils doit être vide.
Exécutez le fichier Python, get_weather
```
python3 weather-agent.py
```

Dans la sortie, vérifiez les noms de fonction locale et distante et assurez-vous que l'outil get_weather est ajouté à l'agent distant. Exemple de sortie :

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.

Dans la console, naviguez jusqu'à la page de détails de l'agent et regardez les mises à jour.
- Dans la page des détails de l'agent, les instructions de routage passent de vide à Perform weather queries using the given tools.
- Sélectionnez Outils. L'outil get_weather apparaît dans la liste des outils.
- Sélectionnez get_weather et, sous Demandes de travail, vérifiez que l'opération CREATE_TOOL a réussi.

Lire les résultats

Dans la sortie, lisez le message de l'utilisateur. Exemple de sortie :


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

Lisez la réponse au clavardage. Exemple de sortie :


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

Lisez l'appel de fonction demandé par l'agent. Exemple de sortie :


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

Lisez le résultat de l'exécution de la fonction. Exemple de sortie :


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

Lisez la demande de clavardage dans l'exemple de sortie de l'agent distant :


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

Lisez la réponse du clavardage à partir de l'exemple de sortie de l'agent distant :


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

Lisez la réponse d'exécution de l'agent en langage naturel. Exemple de sortie :


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

Supprimer l'outil

Dans votre environnement local, créez un fichier nommé list_agent_tools.py avec le contenu suivant. Mettez également à jour toutes les variables d'ID avec vos informations d'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()

Ce script appelle l'opération find_tool du client et retourne tous les outils pour un agent spécifié dans un compartiment spécifié.

Vérifier la sortie :

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

Créez un fichier nommé delete_tools.py et copiez les informations suivantes pour utiliser l'opération delete_tool afin de supprimer weather_tool. Mettez également à jour toutes les variables d'ID avec vos informations d'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()

Dans la console, allez à la page de détails de l'agent et vérifiez que l'outil est supprimé.
Désactivez l'environnement virtuel .
decativate

Documentation sur Oracle Cloud Infrastructure