Ajout d'un outil de fonction à un agent à l'aide d'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 et définies localement en tant qu'outils. Ils sont très flexibles et particulièrement utiles pour les dossiers d'entreprise en raison de leur traitement local, de leur authentification facile et de leur intégration transparente avec les 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.
Remarque
Les outils de fonction sont exécutés localement de votre côté.
La définition de la fonction (nom de la fonction, paramètres de la fonction et leurs descriptions) est envoyée à un agent distant sur les serveurs OCI. Les serveurs OCI n'accèdent pas à l'implémentation de la fonction.
Généralités
Lorsqu'une requête météorologique est effectuée, l'agent distant applique effectivement la classification d'intention pour utiliser l'outil get_weather. Par exemple, en fonction de la requête en langage naturel Is it cold in Seattle?, l'agent distant remplit l'emplacement d'argument et effectue la demande.
L'agent envoie une demande contenant 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.
Le kit de développement d'agent (ADK) effectue les opérations suivantes :
- analyse l'action requise
- trouve la fonction locale enregistrée
- exécute cette fonction avec des 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
Prérequis
- Sur la machine qui exécute 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 l'ADK. Python ADK nécessite Python 3.10 ou une version ultérieure.
pip install "oci[adk]
Configuration d'un compartiment pour le développement
-
Demandez à un administrateur d'ajouter la stratégie IAM suivante pour vous :
allow <a-group-your-user-name-belongs-to> to manage all-resources in compartment <your-compartment-name>Important
Pour un tutoriel, il est pratique de fournir un accès complet à un compartiment. Toutefois, en production, utilisez des stratégies plus restrictives pour limiter l'accès à l'agent. Reportez-vous à Obtention de l'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.
-
Renseignez les informations suivantes :
- Nom :
<your-compartment-name> - Description :
Compartment for <your-description>. - Compartiment parent :
<your-tenancy>(root)
- Nom :
- Sélectionnez Créer un compartiment.
Référence : Création d'un compartiment
Créer un Agent
- Dans la barre de navigation de la console, sélectionnez la région que vous avez sélectionnée pour le fichier de configuration dans la section précédente.
- Sur la page de liste Agents, sélectionnez Créer un agent. Si vous avez besoin d'aide pour trouver la page de liste, reportez-vous à Liste des agents.
-
Entrez les informations suivantes :
- Nom :
<your-agent-name> - Compartiment : sélectionnez le compartiment dans lequel vous êtes autorisé à travailler.
- Description : agent sans outil initial. Ajout d'outils avec ADK.
- Message de bienvenue : laissez ce champ vide.
- Instructions de routage : laissez ce champ vide.
- Nom :
- Sélectionnez Suivant pour accéder à l'étape Ajouter un outil. Ignorez cette page et n'ajoutez aucun outil.
- Sélectionnez Suivant.
- (Facultatif) Sélectionnez Créer automatiquement une adresse pour cet agent afin de créer une adresse lorsque l'agent est créé et de conserver toutes les autres options par défaut.
-
Sélectionnez Suivant, puis Créer un agent.
Remarque
Acceptez les conditions de licence si nécessaire. - Attendez que l'agent devienne actif.
Collecter les informations obligatoires
-
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, sur 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, reportez-vous à 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 l'adresse de cet agent.
-
Copiez l'OCID de l'adresse et collez-le dans un bloc-notes pour la section suivante.
Exemple d'OCID d'adresse :
ocid1.genaiagentendpoint.oc1.us-chicago-1.<unique-id> -
Accédez à 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 personnel.
- 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()
Ajout de l'outil
Important
Si vous avez choisi un agent existant au lieu d'en créer un 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 sur l'agent distant, sauf s'il s'agit de l'outil nommé
Si vous avez choisi un agent existant au lieu d'en créer un 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 sur l'agent distant, sauf s'il s'agit de l'outil nommé
get_weather tool. S'il trouve un outil get_weather distant, il met à jour l'outil distant pour le synchroniser avec l'outil local.-
Dans la console, accédez à la page de détails de l'agent et notez les valeurs correspondantes.
- Instructions de routage : doit être vide.
- Sélectionnez Outils. La liste d'outils doit être vide.
-
Exécutez le fichier Python,
get_weatherpython3 weather-agent.py -
Dans la sortie, vérifiez les noms de fonction locale et distante et assurez-vous que l'outil
get_weatherest 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, accédez à la page de détails de l'agent et regardez les mises à jour.
- Sur la page de 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_weatherapparaît dans la liste des outils. - Sélectionnez get_weather et sous les demandes de travail, vérifiez que l'opération CREATE_TOOL a réussi.
- Sur la page de détails de l'agent, les instructions de routage passent de vide à
Lire les sorties
-
Dans la sortie, lisez le message 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 à la discussion. 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 l'exemple de sortie de la demande de discussion à 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 à la discussion à 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.pyavec 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_tooldu client et renvoie tous les outils d'un agent indiqué dans un compartiment spécifié. -
Examinez le résultat :
[ { "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.pyet copiez les informations suivantes afin d'utiliser l'opérationdelete_toolpour supprimerweather_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, accédez à la page de détails de l'agent et vérifiez que l'outil a été supprimé.
-
Désactivez l'environnement virtuel .
decativate