18 A propos des outils d'agent
Oracle AI Data Platform Workbench prend en charge les modèles d'outil qui peuvent être configurés pour accéder à vos données et répondre à vos cas d'utilisation.
Les agents prennent en charge les configurations composées d'un seul agent pouvant interagir avec un ou plusieurs outils. Le pupitre AI Data Platform propose trois modèles d'outil qui peuvent être configurés pour une utilisation via des flux visuels ou du code :
- Code personnalisé : l'outil Code personnalisé permet aux développeurs d'IA d'implémenter leur outil en Python. Les développeurs regroupent leur outil dans un fichier ZIP, le téléchargent dans leur espace de travail et le configurent en tant que noeud dans leur agent. Les outils de code personnalisés sont conçus pour les cas où les outils intégrés ne fournissent pas l'intégration dont ils ont besoin.
- Demande HTTP : les outils de demande HTTP permettent aux développeurs d'utiliser les appels d'API REST pris en charge dans leurs agents, en tirant parti des API AI Data Platform Workbench et des fonctions qu'ils fournissent. Les agents peuvent utiliser des API REST pour créer des objets d'espace de travail, vérifier les détails, des listes de demandes de dossiers radio ou modifier des objets existants. Pour obtenir la liste complète des API disponibles, reportez-vous à API REST pour Oracle AI Data Platform Workbench.
- Invite : l'outil d'invite permet au développeur d'IA de définir une invite paramétrée qui peut être émise à un LLM pour son choix. Les cas d'utilisation courants d'un outil d'invite incluent les tâches de rédaction d'e-mails, les tâches de traduction, la conversion de style, le message de validation git et les explications de code.
- RAG : l'outil RAG permet aux agents d'extraire les connaissances externes pertinentes avant de générer une réponse. Dans AI Data Platform Workbench, l'outil RAG interroge une base de connaissances (26ai Vector Search) et extrait des blocs de documents sémantiquement pertinents. Ces blocs sont ensuite transmis à l'agent pour génération de réponse.
- SQL : l'outil SQL permet aux agents d'exécuter des requêtes SQL sur des sources de données structurées inscrites via des catalogues externes, tels qu'Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing ou Oracle Autonomous AI Database. L'outil est destiné aux scénarios dans lesquels les requêtes SQL sont prédéfinies et peuvent être paramétrées. L'objectif est de laisser un agent affecter des valeurs aux paramètres. Cet outil n'est pas un outil NL2SQL qui génère une requête SQL basée sur une invite en langage naturel.
Remarques :
L'outil SQL effectue uniquement des interrogations sur les données d'un catalogue externe. Il ne prend pas en charge les données stockées dans un catalogue standard.
Outils de flux d'agents via Visual Flow
Lorsque vous ajoutez des outils aux agents via un flux visuel, vous pouvez trouver des outils sous Modèles d'outil dans votre agent. Pour ajouter un outil à votre agent, faites-le glisser vers le canevas de flux visuel. Après avoir fait glisser le noeud d'outil sur le canevas, le noeud se connecte automatiquement à l'agent.
Chaque outil peut être configuré dans l'onglet Paramètres et testé indépendamment de l'agent en cliquant sur l'onglet Test.
Remarques :
Vous devez attacher un calcul AI à votre agent avant de pouvoir tester un outil système. Si aucun calcul n'est associé, l'onglet Test est désactivé.Outils d'agent via le code LangGraph
Vous ajoutez des outils à vos agents codés LangGraph via une instance de la classe AIDPToolConf().
from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool = AIDPToolConf(name, description, tool_class, conf, params)
- Nom : nom descriptif permettant d'aider les utilisateurs et le LLM à comprendre l'objectif de l'outil.
- Description : résumé complet qui fournit suffisamment d'informations pour que les utilisateurs et les LLM comprennent le rôle de l'outil.
- tool_class : type d'outil pris en charge,
PromptTool,SQLTool,RAGTool,HTTPTooletMCPTool. - conf : configuration de l'outil. Ces informations sont masquées pour le LLM.
- params : paramètres exposés au LLM.
Outil personnalisé
L'outil de code personnalisé permet aux développeurs d'agent d'étendre la plate-forme de données AI avec leur propre code Python.
Vous packagez votre implémentation d'outil en tant que fichier ZIP, vous la téléchargez vers votre espace de travail et vous la configurez en tant que noeud d'outil Code personnalisé dans l'agent. L'agent appelle votre code en tant qu'outil, avec les paramètres fournis par le LLM lors de l'exécution.
L'outil Code personnalisé est destiné aux cas où les outils intégrés (HTTP, SQL, RAG, MCP) ne couvrent pas l'intégration dont vous avez besoin, par exemple lorsque vous devez effectuer un calcul local, analyser un format propre à un domaine ou composer plusieurs étapes qui doivent apparaître à l'agent sous la forme d'un appel d'outil unique.
AI Data Platform Workbench a les limites suivantes lors du téléchargement d'un fichier ZIP avec du code Python pour votre outil de code personnalisé :
| Contrainte | Limite |
|---|---|
| Taille maximale du fichier ZIP | 10 Mo |
| Taille de fichier maximale dans le fichier ZIP | 10 Mo par fichier |
| Taille totale maximale non compressée | 500 Mo |
| Parcours de chemin | Bloqué (../ rejeté) |
Remarques :
Des outils de code personnalisés s'exécutent sur le calcul d'IA attaché à votre agent. Le code a accès à l'environnement de calcul et à l'accès réseau sortant soumis à la configuration réseau de l'espace de travail. Téléchargez uniquement du code à partir de sources fiables.Paramètres de l'outil de code personnalisé
Dans l'onglet Parameters, vous configurez les paramètres statiques de chaque classe d'outil du package. La liste déroulante Classe d'outils vous permet de basculer entre les outils découverts dans le package.
- Classe d'outils : sélectionnez la classe d'outils à configurer. La liste déroulante est renseignée à partir des classes inscrites dans
tool_implementation.py. - Description : description claire et concise de la fonction de l'outil. La description est fournie à l'agent et aide le LLM à décider quand appeler l'outil. La description par défaut est lue à partir du fichier tool_config.json et peut être remplacée ici.
- Configuration : paramètres statiques dont l'outil a besoin lors de l'exécution. Ce sont les clés définies dans l'objet conf de
tool_config.json. Par exemple, timeout, base_dir, max_output_lines et références d'informations d'identification. Les valeurs de configuration prennent en charge les références de paramètre d'exécution{{variable}}. Les variables de session ne sont pas actuellement remplacées par une configuration d'outil personnalisé. Si vous avez besoin d'une valeur de session, transmettez-la en tant que paramètre d'exécution à partir de l'agent. - Définition de l'outil AI : schéma exposé à l'agent, y compris le nom de l'outil, la description et les paramètres d'exécution que l'agent peut transmettre. Le schéma est affiché automatiquement à partir du tableau de schémas dans
tool_config.json.
Création de codes personnalisés
Un package de l'outil Code personnalisé est un fichier ZIP dont la structure est la suivante :
my_tool.zip
├── tool_implementation.py # Required. Contains the tool class(es).
├── tool_config.json # Required. Tool metadata and schema.
├── requirements.txt # Optional. Python dependencies.
├── utils/ # Optional. Helper modules.
│ ├── __init__.py
│ └── helpers.py
├── config/ # Optional. Static configuration files.
│ └── settings.yaml
└── wheels/ # Optional. Bundled wheel files for offline install.
└── humanize-4.15.0-py3-none-any.whl tool_implementation.py
Chaque classe d'outils étend CustomToolBase et est décorée avec @BaseTool.register. La classe doit implémenter la méthode de classe _execute_tool, qui reçoit la configuration de l'outil, les paramètres d'exécution de l'agent et les variables de contexte système, et renvoie une valeur, telle que dict, str ou list.
Voici un exemple de modèle vide d'un élément tool_implementation.py :
"""Custom Code tool implementation."""
from aidputils.agents.tools.custom_tools.base import CustomToolBase
@BaseTool.register
class MyTool(CustomToolBase):
"""Brief description of what the tool does."""
@classmethod
def _validate_config(cls, conf, runtime_params, **context_vars):
"""Optional. Validate configuration before execution.
Raise ValueError to abort the call.
"""
# Example: require an api_key in the tool configuration
if not conf.get("conf", {}).get("api_key"):
raise ValueError("api_key is required")
@classmethod
def _execute_tool(cls, conf, runtime_params, **context_vars):
"""Required. Implement the tool logic.
Args:
conf: the AIDPToolConf dict. User configuration values
live under conf["conf"] when the tool is invoked from
a deployed agent. During a Test run the tool may
receive a flat conf dict; the Developer Toolkit example
below uses a small _get_cfg helper that tolerates both
shapes.
runtime_params: the runtime parameters passed by the
agent at invocation time.
context_vars: system context (such as datalake_id).
Returns:
Any value (dict, str, list, ...). It will be wrapped into
the MCP response by the framework.
To signal a failure, raise an exception:
- ValueError -> INVALID_CONFIG
- any other exception -> TOOL_EXECUTION_ERROR
Do NOT return {"error": "..."}; the framework wraps a
successful return in {"response": ..., "success": True},
so a returned error dict is treated as a normal payload
and the agent will not see it as a failure.
"""
tool_conf = conf.get("conf", conf)
param_value = runtime_params.get("my_param", "")
# Tool logic here
return {"output": f"Processed: {param_value}"}
@classmethod
def _transform_response(cls, response):
"""Optional. Transform the response before MCP formatting."""
return responseFichier_config.json
Le fichier tool_config.json décrit les outils du package : leur nom d'affichage, leur description, leur version, leur schéma de paramètres d'exécution et leurs valeurs de configuration par défaut. Chaque outil enregistré dans tool_implementation.py doit avoir une entrée correspondante dans le tableau des outils.
tool_config.json :{
"displayName": "My Tool Package",
"description": "Brief description of the tool package.",
"tools": [
{
"toolClassName": "MyTool",
"displayName": "My Tool",
"description": "Clear description of when the agent should call this tool.",
"version": "1.0.0",
"schema": [
{
"name": "my_param",
"type": "string",
"description": "What this parameter is for."
}
],
"conf": {
"timeout": 30
}
}
]
}
Types de champ de schéma
L'onglet Parameters du générateur visuel accepte les valeurs String, Number et Boolean. L'exécution accepte un ensemble plus large lors de la création de tool_config.json à la main : int, integer, float, double, number, numeric, bytes, list, array, sequence, dict, map, mapping, set, tuple, none, null, plus les formes génériques telles que list[int]. Ces types plus larges sont utilisables à partir de JSON mais ne sont pas affichés dans la liste déroulante de l'interface utilisateur.
requirements.txt
Le fichier requirements.txt répertorie les dépendances Python dont votre outil a besoin. La syntaxe pip standard est prise en charge, y compris les spécificateurs de version et les commentaires. Le fichier est facultatif. Si votre outil utilise uniquement la bibliothèque standard Python ou les packages préinstallés, vous n'avez pas besoin d'un élément requirements.txt.
Voici un exemple vierge de requirements.txt :
# List third-party dependencies one per line.
# Examples:
# humanize>=4.0
# python-dateutil>=2.8,<3.0
# beautifulsoup4==4.12.3 AI Data Platform Workbench filtre les dépendances dans requirements.txt avant de les installer sur le calcul AI, afin d'éviter les conflits d'exécution avec la plate-forme elle-même. Les règles de filtrage sont les suivantes :
| Catégorie | Exemple | Action |
|---|---|---|
| Packages de plate-forme | langgraph, langchain-core, langchain-oci, langchain_mcp_adapters, pyyaml | Rejeté (interromprait l'exécution de l'agent). |
| Packages préinstallés | oci, requêtes, request-toolbelt, websockets, cryptographie, certifici, pyopenssl, urllib3, pydantic, pydantic-core, pydantic-settings, numpy, oracledb, sqlalchemy, aiohttp, httpx, httpx-sse, anyio, jsonschema, orjson | Ignoré (déjà disponible, pas besoin de déclarer). |
| Installations URL ou VCS | git+https ://..., -e ./local_pkg | Bloqué (sécurité). |
| Tout le restant | humaniser, bellesoup4, jmespath | Installé. |
Remarques :
Les dépendances déclarées dansrequirements.txt sont installées pendant le déploiement complet de l'agent. Les dépendances ne sont pas installées lors d'une seule exécution de test à partir du panneau de configuration. Si votre outil dépend de packages tiers, déployez d'abord l'agent, puis utilisez l'outil à partir du Playground de test.
Pour les outils qui ont besoin de dépendances qui ne sont pas préinstallées et où l'installation déterministe et hors ligne est importante, vous pouvez regrouper les fichiers .whl dans un répertoire roues/ à la racine du ZIP. La plate-forme s'installe d'abord à partir du répertoire local wheels et ne revient à l'index de package que si nécessaire. C'est l'approche recommandée pour les outils de production.
Roues de regroupement pour installation hors ligne
pip download \
--dest wheels/ \
--platform manylinux_2_28_x86_64 \
--python-version 3.11 \
--only-binary=:all: \
-r requirements.txt
Crochets de cycle de vie des outils
Les outils de code personnalisés prennent en charge trois méthodes de cycle de vie. Seul _execute_tool est requis.
| Méthode | Quand appelé | Description |
|---|---|---|
| _validation_config | Avant _execute_tool | Valide la configuration. Déclenchez ValueError pour abandonner l'appel avant son exécution. |
| _outil d'exécution | Sur chaque appel d'outil | Requis. Implémente le comportement de l'outil. Renvoie toute valeur (dict, str, list) et génère une exception pour signaler un échec (ValueError → INVALID_CONFIG, toute autre exception → TOOL_EXECUTION_ERROR). N'utilisez pas d'erreur {"error" : "..."} renvoyée car elle est traitée comme une charge utile normale. |
| _transform_response | Après _execute_tool | Transformez la réponse avant qu'elle ne soit encapsulée au format MCP et retournée à l'agent. |
| modèle_invite | chaîne | Modèle d'invite utilisé par le LLM, avec des variables au format {{variable}} pour insertion dynamique |
Valeurs de configuration et paramètres d'exécution
Les outils de code personnalisé ont deux sources d'entrée distinctes qui sont faciles à confondre. Les valeurs de configuration proviennent de la section Configuration de l'onglet Paramètres et sont intégrées à l'outil lorsque l'agent est déployé. Les paramètres d'exécution proviennent de l'agent au moment de l'appel et sont différents à chaque appel.
- Les valeurs de configuration sont accessibles via conf.get("conf", conf). Utilisez-les pour des choses qui ne changent pas entre les appels : URL de base, références d'informations d'identification, délais d'attente, limites de sortie.
- Les paramètres d'exécution sont accessibles via runtime_params.get("nom"). Utilisez-les pour les valeurs que l'agent décide réellement au moment de l'appel : la requête, le chemin du fichier et le corps de la demande.
Remarques :
Les valeurs de configuration peuvent passer par la substitution de modèle et peuvent arriver sous forme de chaînes même lorsque vous les avez définies sous forme de nombres. Forcer toujours les valeurs de configuration numériques de manière défensive, par exemple :int(tool_conf.get("timeout", 30)).
Plusieurs outils par package
Un code postal unique peut contenir plusieurs classes d'outils. Chaque classe enregistrée avec @CustomToolBase.register devient un outil distinct dans l'agent. Le panneau Outils de l'onglet Package répertorie tous les outils repérés et vous permet d'activer chacun indépendamment. Chaque outil est configuré séparément dans l'onglet Paramètres via la liste déroulante Classe d'outils.
Outil de code via LangGraph Code
Dans le générateur de code, un outil de code personnalisé est enregistré via la bibliothèque Python aidpUtils en référençant le package téléchargé et en sélectionnant l'une de ses classes d'outil.
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf
hello_tool_conf = AIDPToolConf(
name="hello_tool",
description="Returns a hello world greeting.",
tool_class="HelloTool", # the class registered with @BaseTool.register
conf={}, # values from tool_config.json "conf"; supports {{variable}} substitution
params=[
{"name": "name", "type": "string",
"description": "Name to greet."}
],
)
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())
tool_class doit être le nom de classe exact enregistré via @BaseTool.register dans tool_implementation.py. La structure recherche la classe dans BaseTool.tool_class_registry[tool_class]. conf met en miroir l'objet conf de l'entrée correspondante dans tool_config.json.
Remarques :
Ne placez paspackage_path ou tool_class_name dans conf car ils ne sont pas consommés.
Agent de test - Outils de code personnalisé
L'onglet Test vous permet d'exécuter l'outil sans exécuter l'agent complet. Indiquez les valeurs des paramètres d'exécution et des variables de session référencées dans la configuration, puis cliquez sur Exécuter pour appeler l'outil et afficher la réponse.
Remarques :
Si votre outil dépend de packages tiers déclarés dansrequirements.txt, les dépendances sont installées pendant le déploiement complet de l'agent, et non pendant une seule exécution de test. Pour tester le code qui dépend de packages supplémentaires, déployez d'abord l'agent, puis appelez l'outil à partir du Playground de test.
Ajout d'un outil personnalisé à un agent
Vous pouvez ajouter un outil personnalisé à vos agents pour vous permettre d'utiliser votre propre code Python pour étendre AI Data Platform.
Remarques :
Un calcul d'IA doit être associé à votre agent avant d'ajouter un outil de code personnalisé. Le calcul AI est requis pour installer les dépendances et exécuter l'outil.- Dans l'onglet Package, cliquez pour sélectionner le fichier ZIP contenant votre code personnalisé ou faites-le glisser vers l'écran. Attendez que le chargement soit terminé.
- Consultez la liste des outils repérés dans la section Outils de l'onglet Package. Chaque classe d'outil figurant dans
tool_implementation.pyest répertoriée avec son nom, sa description et sa version.
- Facultatif : cliquez sur l'onglet Test. Indiquez les paramètres de test et cliquez sur Soumettre. Reportez-vous aux résultats du test dans le panneau Résultats du test.
Outil de serveur MCP distant
Les développeurs de flux d'agent peuvent connecter leurs flux d'agent à des serveurs MCP (Remote Model Context Protocol) à l'aide de l'outil Serveur MCP distant.
L'outil MCP est disponible à la fois dans le générateur visuel et dans les expériences du générateur de code. Dans l'expérience du générateur de code, la connexion MCP peut être configurée via la bibliothèque Python aidpUtils. Dans cette section, nous vous présentons les expériences du générateur visuel et du générateur de code.
Remarques :
Cette fonctionnalité prend en charge les serveurs MCP avec des transports HTTP transmissibles (serveurs distants). Les serveurs MCP stdio-transport locaux ne sont pas pris en charge.Informations d'identification MCP dans la banque d'informations d'identification Oracle AI Data Platform Workbench
Lors de la configuration du serveur MCP, vous devez indiquer si le serveur MCP distant requiert l'option Aucune authentification ou un jeton Bearer. Si votre serveur MCP nécessite un jeton d'authentification, ce jeton doit être ajouté à votre banque d'informations d'identification pour pouvoir être référencé par le serveur MCP.
Lorsque vous créez des informations d'identification de serveur MCP, vous sélectionnez l'option Jeton secret pour Type d'informations d'identification, puis fournissez la clé d'identificateur, telle qu'une clé d'API et la valeur de jeton. Pour plus d'informations, reportez-vous à Création d'informations d'identification (aperçu).
Remarques :
Une seule information d'identification peut contenir plusieurs clés.Les serveurs MCP disponibles publiquement ne nécessitent pas d'authentification supplémentaire. Par exemple, la connexion à https://mcp.deepwiki.com/mcp ressemble à ce qui suit :
Exposition des outils MCP à l'agent
Une fois qu'une connexion au serveur MCP distant a été établie, vous pouvez commencer à configurer les outils hébergés sur le serveur que vous souhaitez exposer à votre agent. Le panneau de configuration du serveur MCP est affiché ci-dessous dans le cas du serveur DeepWiki MCP.
Sur la gauche, l'onglet Outils affiche la liste des outils disponibles sur le serveur MCP. Vous devez ajouter des outils pour les exposer à votre agent. Pour ce faire, cliquez sur l'option Ajouter tout pour afficher tous les outils en même temps ou sur l'option Ajouter de chaque outil pour sélectionner un sous-ensemble des outils.
Dans l'exemple ci-dessous, nous avons ajouté deux outils (read_wiki_structure, read_wiki_structure). Vous pouvez enlever des outils en cliquant sur Enlever.
Le panneau de droite de l'onglet Outils fournit de la documentation sur chaque outil, y compris le nom de l'outil, la description de l'outil ainsi que les paramètres de l'outil. Dans la capture d'écran ci-dessous, je montre un exemple pour l'outil serveur GitHub MCP add_comment_to_pending_review.
Oracle AI Data Platform Workbench fournit quelques contrôles supplémentaires sur chaque outil. Vous pouvez masquer les paramètres de l'agent et leur affecter des valeurs. Par exemple, dans GitHub, vous pouvez choisir que votre agent ne commente qu'un seul référentiel prédéterminé, tel que oracle-aidp-samples. Pour ce faire, désactivez le paramètre repo et affectez une valeur par défaut dans la zone de texte :
Dans le champ Instructions sur l'outil, vous pouvez également remplacer la description de l'outil et fournir une autre description avec des instructions supplémentaires. Pour la plupart des cas d'utilisation, nous vous recommandons d'adopter la description fournie par le serveur MCP.
Outil de serveur MCP distant via le code LangGraph
La bibliothèque Python aidpUtils permet aux développeurs de sélectionner un serveur MCP distant et d'exposer un sous-ensemble de ses outils à un agent construit avec LangGraph. Pour consulter la référence de l'API aidputils, reportez-vous à API Aidp-utils pour Oracle AI Data Platform Workbench.
Vous pouvez créer un ensemble d'outils autorisés en créant une instance de build_structured_tools_from_allowed_mcp_tools :
from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools
TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>,
server_name=<MCP_SERVER_NAME>,
endpoint=<MCP_ENDPOINT>,
transport="streamable_http",
auth=<MCP_AUTH>,
headers={}
)- <MCP_SERVER_NAME> est un nom d'affichage que vous voulez donner à votre serveur MCP. Il est utilisé à des fins de documentation et n'est pas exposé à l'agent.
- <MCP_ENDPOINT> est l'adresse du serveur MCP (par exemple, https://api.githubcopilot.com/mcp/)
- <MCP_AUTH> est un dictionnaire avec la clé "authType". Cette clé peut prendre deux valeurs :
NO_AUTHouBEARER_TOKEN. Dans le cas deBEARER_TOKEN, une autre clé est attendue : "jeton" avec la valeur du jeton au porteur. - <ALLOWED_MCP_TOOLS> est la liste des outils du serveur MCP à exposer à l'agent. Chaque outil a besoin d'une définition d'outil JSON complète suivant le protocole MCP.
Voici un exemple :
MCP_SERVER_NAME = "test_mcp"
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp"
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }
{
"ALLOWED_TOOLS": [
{
"tool": {
"name": "get_current_weather",
"description": "Get current weather for a given city with advanced options.",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"unit": {
"type": "string",
"default": "metric"
},
"include_historical": {
"type": "boolean",
"default": false
},
"detailed": {
"type": "boolean",
"default": true
},
"timeout": {
"type": "integer",
"default": 30
}
},
"required": [
"city"
]
}
},
"instruction": "",
"argOverrides": {}
},
{
"tool": {
"name": "get_forecast",
"description": "Get forecast for a given city with customizable options.",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"days": {
"type": "integer",
"default": 5
},
"unit": {
"type": "string",
"default": "metric"
},
"include_alerts": {
"type": "boolean",
"default": false
},
"detailed": {
"type": "boolean",
"default": true
},
"hourly": {
"type": "boolean",
"default": false
}
},
"required": [
"city"
]
}
},
"instruction": "",
"argOverrides": {}
}
]
}
MCP_HEADERS = {}
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
server_name=MCP_SERVER_NAME,
endpoint=MCP_ENDPOINT,
transport="streamable_http",
auth=MCP_AUTH,
headers=MCP_HEADERS,
)
L'objet TOOLS peut ensuite être utilisé lors de la création d'une instance d'agent avec langchain.agent create_agent dans la méthode setup() de la définition de l'agent de classe :
def setup(self):
logger.info("Initializing TestMcpAgent")
oci_llm = init_oci_llm(llm_conf)
system_prompt = textwrap.dedent(
"""
You're a weather agent. Append 12345 to every response.
"""
).strip()
self.agent = create_agent(
name="test_mcp_high_code",
model=oci_llm,
tools=TOOLS,
system_prompt=system_prompt,
debug=True,
)
logger.info("Agent ready.")Si vous utilisez une variable de session pour stocker la valeur d'un jeton de support, une référence à une variable de session créée précédemment peut être affectée à la clé de jeton du dictionnaire de configuration d'authentification. Exemple :
test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=test_mcp_mcp_allowed_tools,
server_name="test_mcp",
endpoint="http://144.25.36.217:9301/mcp",
transport="streamable_http",
auth=test_mcp_mcp_auth_config,
headers={}
)Exemples de code pour les outils distants du serveur MCP
Nous fournissons des exemples de code de bout en bout pour plusieurs scénarios MCP dans le référentiel GitHub d'exemples AI Data Platform Workbench.
Tester les outils distants du serveur MCP
Une fois les outils sélectionnés, l'étape suivante consiste généralement à tester des outils individuels pour s'assurer qu'ils se comportent comme prévu. Cela peut être fait via l'onglet Test du nœud d'outil MCP.
Sélectionnez l'un des outils que vous avez ajoutés dans l'onglet Outils, indiquez les valeurs des paramètres et cliquez sur le bouton Tester.
La sortie de l'outil s'affiche dans le panneau de droite.
L'onglet Détails fournit des informations sur la méthode d'authentification, l'URL du serveur MCP et la description.
Le bouton Modifier en regard de la méthode d'authentification vous permet de modifier la configuration du noeud d'outil MCP distant. Vous pouvez modifier le nom d'affichage, la description et le jeton de support utilisés lors de l'établissement de la connexion :
Connecter un agent à un serveur MCP distant à partir de Visual Builder
Vous pouvez ajouter l'accès à un serveur MCP distant à votre agent en faisant glisser le noeud d'outil du serveur MCP personnalisé vers le canevas.
Remarques :
Le calcul AI hébergeant l'agent hérite des paramètres réseau de son espace de travail. Si vous activez l'accès au réseau privé pour l'espace de travail hébergeant le calcul AI, votre agent peut uniquement atteindre les serveurs MCP hébergés dans le VCN et le sous-réseau privés sélectionnés. Votre agent peut ne pas être en mesure d'atteindre les serveurs HTTP distants disponibles sur le réseau Internet public.- Accédez à votre agent.
- Dans l'onglet Flux, sous Modèles d'outil, cliquez sur le serveur MCP personnalisé et faites-le glisser vers le canevas.
- Indiquez l'URL du serveur pour votre serveur MCP.
- Indiquez un nom d'affichage pour votre serveur MCP. Il s'agit du nom du noeud affiché dans le canevas du générateur visuel.
- Facultatif : indiquez une description pour le serveur MCP. Le champ de description n'est pas fourni à l'agent.
- Dans le menu déroulant Authentification, sélectionnez une méthode d'authentification.
- Aucune authentification : utilisez cette option si le serveur MCP distant est disponible publiquement et ne nécessite aucune authentification.
- Jeton de support : utilisez cette option si le serveur MCP distant requiert un jeton d'authentification. Vous devez stocker la clé d'API dans la banque d'informations d'identification Oracle AI Data Platform Workbench et fournir une référence à l'entrée de banque d'informations d'identification.
- Cliquez sur Connexion. AI Data Platform Workbench teste la connexion et signale le résultat.
Outil de requête HTTP
L'outil de demande HTTP permet à l'agent d'appeler n'importe quelle API REST HTTPS.
Vous configurez la demande, y compris la méthode, l'URL, les en-têtes, les paramètres de requête, le corps de la demande, l'authentification et, éventuellement, une étape d'optimisation de la réponse. L'agent appelle ensuite l'adresse lors de l'exécution. L'outil de demande HTTP est disponible dans le générateur visuel et dans le générateur de code. Dans le générateur de code, l'outil est configuré via la bibliothèque Python aidpUtils.
Remarques :
L'outil de demande HTTP ne prend en charge que les demandes https :// et HTTP ://. Les connexions de socket Web (ws/wss), les téléchargements de fichiers binaires et les certificats auto-signés ne sont pas pris en charge.Remarques :
Le calcul AI hébergeant l'agent hérite des paramètres réseau de son espace de travail. Si vous activez l'accès au réseau privé pour l'espace de travail hébergeant le calcul AI, votre agent n'atteindra que les adresses HTTP dans le VCN et le sous-réseau privés sélectionnés. Votre agent ne peut pas atteindre les adresses disponibles sur le réseau Internet public.Les paramètres suivants doivent être fournis lors de la configuration d'un outil de demande HTTP :
| Configuration | Description |
|---|---|
| Méthode HTTP | Verbe HTTP à utiliser. Les méthodes prises en charge sont GET, POST, PUT, PATCH et DELETE. |
| URL | URL complète de l'adresse cible. L'URL prend en charge les références de variable de session {{sessionVariables.variable_name}} et les références de paramètre d'exécution {{variable}}. Par exemple : https://api.example.com/users/{{user_id}}/orders.
|
| Délai d'expiration | Durée maximale pendant laquelle l'outil attend une réponse de l'adresse distante. La valeur par défaut est 30 secondes et la valeur maximale est 300 secondes. |
| Type d'authentification | Méthode d'authentification à utiliser lors de l'appel de l'adresse. Reportez-vous à la section Authentification ci-dessous pour obtenir la liste des méthodes d'authentification prises en charge. |
Remarques :
Des outils de code personnalisés s'exécutent sur le calcul d'IA attaché à votre agent. Le code a accès à l'environnement de calcul et à l'accès réseau sortant soumis à la configuration réseau de l'espace de travail. Téléchargez uniquement du code à partir de sources fiables.En-têtes
Les en-têtes sont des paires clé-valeur envoyées avec la demande HTTP. Vous pouvez ajouter autant d'en-têtes que nécessaire en cliquant sur le bouton Ajouter. Les valeurs d'en-tête peuvent référencer des variables de session et des paramètres d'exécution à l'aide de la syntaxe {{variable_name}}
Remarques :
Pour les en-têtes sensibles, vous devez utiliser le champ Type d'authentification pour vous assurer que les informations d'identification sont injectées en toute sécurité à partir de la banque d'informations d'identification. L'autorisation, le cookie et la clé X-API-Key sont des en-têtes sensibles et ne peuvent pas être définis via la section En-têtes.Paramètres de requête
Les paramètres de requête sont ajoutés à l'URL en tant que chaîne de requête. Vous pouvez ajouter autant de paramètres de requête que nécessaire en cliquant sur le bouton Ajouter. Comme les en-têtes, les valeurs de paramètre de requête peuvent référencer des variables de session et des paramètres d'exécution.
Description
Le champ de description décrit ce que l'outil fait, quand il doit être utilisé et quel type de sorties ou d'effets il produit. La description est fournie à l'agent et aide le LLM à décider quand appeler l'outil.
- • Objectif : Expliquez ce que l'outil est conçu pour faire en une phrase claire. Exemple : "Cet outil extrait les tickets d'assistance client d'une base de connaissances et les résume par niveau de priorité."
- Quand l'utiliser : décrivez les conditions dans lesquelles l'agent doit appeler cet outil par rapport à un autre.
- Entrées et sorties : décrivez brièvement les paramètres dont l'outil a besoin et la forme de ce qu'il renvoie.
Authentification de demande HTTP
L'outil de demande HTTP prend en charge plusieurs méthodes d'authentification. Sélectionnez la méthode appropriée dans la liste déroulante Type d'authentification.
| Type d'authentification | Description |
|---|---|
| Aucune authentification | Aucune authentification n'est ajoutée à la demande. Utilisez-le pour les adresses accessibles publiquement. |
| Principal de ressources OCI | La demande est signée à l'aide du principal de ressource OCI du calcul AI. Utilisez-le lorsque vous appelez des services OCI tels qu'Object Storage ou le service OCI Generative AI. L'accès est régi par les stratégies OCI IAM. |
| Authentification de base | Un nom d'utilisateur et un mot de passe sont codés et envoyés dans l'en-tête d'autorisation. Les informations d'identification doivent être stockées dans la banque d'informations d'identification. |
| Jeton de porteur | Un jeton porteur est envoyé dans l'en-tête d'autorisation. Le jeton doit être stocké dans la banque d'informations d'identification. |
| Authentification d'en-tête | Une clé d'API est envoyée dans un en-tête personnalisé (par exemple, X-API-Key). Le nom d'en-tête est configurable et la valeur de clé doit être stockée dans la banque d'informations d'identification. |
Lorsque vous sélectionnez une méthode d'authentification nécessitant une clé secrète, le panneau de configuration affiche un sélecteur d'informations d'identification. Cliquez sur le sélecteur d'informations d'identification pour sélectionner des informations d'identification précédemment stockées ou créez-en une à partir de la banque d'informations d'identification. Reportez-vous à la section Stockage d'informations d'identification dans la section Banque d'informations d'identification de la documentation du serveur MCP pour la procédure pas à pas.
Variables de session et paramètres d'exécution
Les variables de session peuvent être référencées dans l'URL, les valeurs d'en-tête, les valeurs de paramètre de requête et le corps de la demande à l'aide de la syntaxe {{sessionVariables.variable_name}}. Les paramètres d'exécution transmis par l'agent lors de l'appel peuvent être référencés à l'aide de la syntaxe {{variable_name}}.
https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/oLorsque l'outil est exécuté, {{sessionVariables.region}} est remplacé par la valeur de la variable de session de région pour la session en cours et {{bucket}} est remplacé par la valeur transmise par l'agent lors de l'appel.
Remarques :
Les valeurs de modèle sont encodées automatiquement par URL lorsqu'elles sont remplacées dans les paramètres d'URL ou de requête. Vous n'avez pas besoin de les encoder vous-même.Définition de l'outil AI
La partie droite du panneau de configuration affiche la définition de l'outil AI. Il s'agit du schéma exposé à l'agent. Il inclut le nom de l'outil, sa description et la liste des paramètres d'exécution que l'agent peut transmettre lors de l'appel de l'outil. La définition de l'outil AI est générée automatiquement à partir du champ Description et des espaces réservés {{variable}} détectés dans l'URL, les en-têtes, les paramètres de requête et le corps.
Le panneau de définition de l'outil AI est le panneau situé à droite du panneau de configuration de l'outil HTTP affiché précédemment dans ce document. Tant que vous n'avez pas fourni de description et défini au moins un paramètre d'exécution, le volet de définition de l'outil AI affiche un message d'espace réservé. Une fois que vous avez renseigné la description et référencé au moins un élément {{variable}} dans l'URL, les en-têtes, les paramètres de requête ou le corps, le schéma est affiché dans le volet.
Optimisation de la réponse pour l'agent
De nombreuses API renvoient des réponses volumineuses qui incluent des champs dont l'agent n'a pas besoin. L'envoi de la réponse entière à l'agent consomme des jetons et peut dégrader la qualité du raisonnement de l'agent. L'outil de requête HTTP fournit une section d'optimisation de réponse qui vous permet de réduire la charge utile de réponse avant qu'elle ne soit renvoyée à l'agent.
- Sélection de champ JSON : sélectionnez un sous-ensemble de champs à partir d'une réponse JSON. Vous pouvez indiquer un chemin vers un objet imbriqué à l'aide de la notation par points (telle que data.results) et d'une liste de champs à inclure ou à exclure.
- Sélecteur CSS HTML : extrait un sous-ensemble d'une réponse HTML à l'aide d'un sélecteur CSS (tel que article.content). Supprimez éventuellement les balises HTML pour ne renvoyer que du texte.
- Troncation de texte : limitez la réponse à un nombre maximal de caractères pour éviter les réponses de texte trop volumineuses.
Traitement des erreurs et codes d'erreur
Lorsque la demande HTTP échoue, l'outil renvoie une réponse d'erreur structurée à l'agent. L'erreur inclut un code d'erreur, un message lisible par l'utilisateur et des détails sur l'échec. L'agent peut utiliser ces informations pour décider s'il doit réessayer, revenir à un autre outil ou signaler l'échec à l'utilisateur.
| Code d'erreur | Catégorie | Signification | Nouvelle tentative possible |
|---|---|---|---|
| DÉLAI D'ATTENTE DE CONNEXION | Réseau | L'adresse distante n'a pas répondu dans le délai d'expiration configuré. | Oui |
| ECHEC DE DNS | Réseau | Le nom d'hôte dans l'URL n'a pas pu être résolu. | Oui |
| CONNEXION_REFUSÉE | Réseau | L'adresse distante a refusé la connexion. | Oui |
| ERREUR_CERTIFICAT_SL | TLS | Impossible de valider le certificat TLS de l'adresse distante. | No |
| NON AUTORISÉ | HTTP 401 | L'adresse distante a rejeté les informations d'identification. Vérifiez que la référence des informations d'identification est valide et n'a pas expiré. Pour le principal de ressource OCI, vérifiez que le calcul AI dispose d'un principal de ressource actif dans cet environnement. | No |
| INTERDIT | HTTP 403 | Les informations d'identification ont été authentifiées mais ne disposent pas des droits d'accès nécessaires pour la ressource demandée. Vérifiez les portées d'API, les droits d'accès ou la stratégie IAM attachés à la ressource. | No |
| INTROUVABLE | HTTP 404 | L'adresse distante n'a pas trouvé la ressource demandée. | No |
| DÉBIT_LIMITÉ | HTTP 429 | L'adresse distante limite le débit de l'appelant. Réessayez après le délai indiqué par l'en-tête Retry-After. | Oui |
| ERREUR_SERVEUR | HTTP 5xx | L'adresse distante a renvoyé une erreur de serveur. Souvent un problème transitoire. | Oui |
| SERVICE_NON DISPONIBLE | HTTP 503 | L'adresse distante est temporairement indisponible. | Oui |
| INVALID_TEMPLATE | Validation | Impossible de résoudre une référence {{variable}}. Vérifiez que toutes les variables de session et tous les paramètres d'exécution référencés sont définis et ont une valeur au moment de l'appel.
|
No |
| URL NON VALIDE | Validation | L'URL est mal formée, utilise un protocole non pris en charge ou se résout en une adresse bloquée (par exemple, une adresse IP privée ou une adresse de métadonnées cloud). | No |
| RÉPONSE_TROP ÉLEVÉE | Validation | La réponse a dépassé la taille de réponse maximale de 10 Mo. | No |
| LIMITE DE TAUX DÉPASSÉE | Plate-forme | L'agent a dépassé la limite de taux de demandes par agent de la plate-forme (60 demandes par minute) ou la limite de simultanéité (10 demandes simultanées). | Oui |
Chaque réponse d'erreur comprend un champ de guidage avec une étape suivante suggérée, et un champ de détails avec le temps écoulé et tout contexte spécifique à l'erreur tel que le code de statut HTTP.
Outil de requête HTTP via le code LangGraph
Depuis le générateur de code, l'outil HTTP Request est configuré via la bibliothèque Python aidpUtils. Définissez une valeur AIDPToolConf avec tool_class définie sur HttpEndpointTool et transmettez le dictionnaire de configuration dans le champ conf.
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf
weather_http_tool_def = {
"method": "GET",
"url": "https://api.openweathermap.org/data/2.5/weather",
"params": {
"q": "{city}",
"units": "metric",
"appid": "{api_key}"
},
"auth_type": "NO_AUTH",
"auth_config": {}
}
weather_http_tool_params = [
{"name": "city", "type": "string",
"description": "Name of the city."},
{"name": "api_key", "type": "string",
"description": "OpenWeather API key."}
]
weather_http_tool_conf = AIDPToolConf(
name="get_weather",
description="Get current weather for a city.",
tool_class="HttpEndpointTool",
conf=weather_http_tool_def,
params=weather_http_tool_params
)
weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())
Le dictionnaire Conf prend en charge les mêmes champs que le générateur visuel : méthode, URL, en-têtes, paramètres, corps, auth_type, auth_config et response_optimization. La liste des paramètres définit les paramètres d'exécution que l'agent peut transmettre.
| type_authentification | Champs auth_config |
|---|---|
| NO_AUTH | {} (vide)
|
| RESOURCE_PRINCIPAL | {} (vide)
|
| AUTH_DE BASE | nom utilisateur, mot de passe (ou nom utilisateur_vault_id, mot de passe_vault_id pour les informations d'identification dans OCI Vault) |
| PORTEUR_AUTH | porteur_jeton (ou porteur_jeton_vault_id) |
| API_KEY_AUTH | api_key (ou api_key_vault_id), header_name (X-API-Key par défaut) |
| INFORMATIONS D'IDENTIFICATION DE CLIENT OAUTH2_CREDENTIALS | token_endpoint, scope, client_id, client_secret (ou client_id_vault_id, client_secret_vault_id) |
Agent de test - Outils de code personnalisé
L'onglet Test vous permet d'exécuter l'outil sans exécuter l'agent complet. Indiquez les valeurs des paramètres d'exécution et des variables de session référencées dans la configuration, puis cliquez sur Exécuter pour appeler l'outil et afficher la réponse.
Le panneau de réponse affiche le code de statut HTTP, les en-têtes de réponse, le corps de la réponse et le temps écoulé en millisecondes. Si l'optimisation de la réponse est activée, la réponse optimisée est également affichée avec la réponse brute.
Ajout d'un outil de requête HTTP à un agent
Vous pouvez ajouter un outil de demande HTTP à vos agents pour vous permettre d'appeler des API REST HTTPS.
Remarques :
Un calcul d'IA doit être associé à votre agent avant d'ajouter un outil de code personnalisé. Le calcul AI est requis pour installer les dépendances et exécuter l'outil.- Dans les modèles d'outil, glissez-déplacez un outil de demande HTTP vers votre canevas.
- Fournissez les en-têtes de votre demande HTTP. Cliquez sur Ajouter un nouvel pour ajouter des en-têtes supplémentaires.
- Indiquez les paramètres de requête pour votre demande HTTP. Cliquez sur Ajouter un nouveau pour ajouter des paramètres supplémentaires.
- Facultatif : cliquez sur l'onglet Test. Indiquez les paramètres de test et cliquez sur Soumettre. Reportez-vous aux résultats du test dans le panneau Résultats du test.
Outil d'invite
L'outil d'invite vous permet d'appeler un LLM dans un agent d'IA avec une invite de modèle et renvoie la réponse du LLM à l'agent.
Les invites que vous fournissez au LLM peuvent inclure des paramètres identifiés par des accolades doubles, par exemple {{PARAMETER_NAME}}. Les valeurs de paramètre sont affectées par l'agent lors de l'appel de l'outil.
Quand utiliser les outils d'invite
- Votre invite est longue et nécessite des instructions de format détaillées qui couvrent plusieurs jetons des années 100.
- L'intégration de l'invite dans les instructions de l'agent augmenterait l'utilisation du contexte et augmenterait considérablement les coûts, en particulier si l'on adopte un LLM SOTA pour son agent.
- On veut minimiser la taille des instructions données à l'agent pour réduire les coûts.
- La tâche définie par l'outil d'invite peut être gérée par un LLM plus petit et plus rapide que le modèle de raisonnement utilisé par l'agent. Les modèles plus petits sont généralement rentables et, dans certains cas, peuvent être spécialisés pour générer des données dans une modalité ou un format particulier.
- Un outil d'invite permet aux paramètres d'entrée structurés de contrôler la génération de sortie. Si votre cas d'utilisation peut être paramétré et que la génération peut varier d'une session à l'autre, l'encapsulation de la génération dans un outil d'invite est logique.
En outre, l'encapsulation des instructions de génération dans un outil rapide suit de nombreuses bonnes pratiques d'architecture d'agent modernes, notamment la réutilisation des outils, la maintenabilité, la modalité, la cohérence des résultats, l'évolutivité et la gouvernance. Voici quelques exemples de cas d'utilisation :
- Génération d'e-mails, de rapports, de résumés, d'articles, etc. suivant une structure prédéfinie et approuvée qui peut être utilisée comme modèle
- Génération de sorties JSON complexes
- Addition, extraction de phrases clés, tâches d'explication sur les documents
- Génération de la requête
- Génération de modalités spécifiques (images, vidéos, audio, données de nuage de points, etc.) optimisées pour un modèle spécifique
Outils d'invite via Visual Flow
Voici un exemple d'outil d'invite créé via un flux visuel qui demande à un LLM de générer des titres d'article de blog en fonction d'un sujet affecté par l'agent :
Vous êtes un maître stratège de blog. Votre tâche est de réfléchir à des idées de billets de blog convaincantes basées sur un sujet donné. Pour le {{topic} donné, générez 5 titres de blog uniques. Pour chaque titre, incluez une description en une phrase de l'angle que prendrait le billet. Présentez la sortie sous forme de liste numérotée.
- Nom de l'outil : utilisez un nom descriptif pour l'outil afin de guider l'agent. Dans cet exemple, nous suggérons
blog_ideas. Évitez d'utiliser des noms inutiles comme tool123.
- Description de l'outil : fournissez une description complète de ce que fait l'outil. S'il existe des limites à l'outil ou s'il existe des scénarios dans lesquels l'outil ne doit pas être utilisé, répertoriez-les dans le champ de description.
- Région OCI et LLM de service d'IA générative : sélectionnez la région OCI pour remplir la liste des LLM disponibles dans cette région, puis sélectionnez votre LLM.
- Paramètres LLM : les paramètres tels que les jetons de sortie maximum, la température et le p supérieur sont configurés dans l'onglet Paramètres du modèle. Si vous n'affectez aucune valeur, les valeurs par défaut du service OCI Generative AI sont utilisées.
- Requête : L'invite utilisée pour définir l'objectif de l'outil est définie dans le champ Requête.
Les paramètres que vous définissez dans l'invite renseignent automatiquement le panneau de définition de l'outil AI. Fournissez à votre agent une description de chaque paramètre, ainsi que le type de paramètre et la valeur par défaut, le cas échéant.
Outil d'invite via le code LangGraph
Si vous créez votre agent via du code, vous pouvez configurer le même outil d'invite dans l'exemple de flux visuel comme suit :
prompt_config = {
"llm": {
"model_id" : "xai.grok-4",
"model_provider" : "generic",
"compartment_id" : "<your-compartment-ocid>",
"endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
}, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
"name" : "topic",
"type" : "string",
"description" : "Blog topic",
"defaultValue" : "golf"
} ]
Instanciez ensuite AIDPToolConf comme suit :
blogger_tool = AIDPToolConf(name="blog_posts_topics",
description= "Write blog posts ideas about a particular topic. ",
tool_class = "PromptTool", conf=prompt_config params=prompt_params)
Enfin, vous créez un outil compatible LangGraph avec la fonction utilitaire create_langgraph_tool() à partir d'aideputils :
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())
Vous ajoutez l'outil nouvellement créé à un agent ReAct. Dans LangGraph, le code se présente comme suit :
tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>,
tools=tools_agent1,
prompt=<system_prompt>,
debug=True, checkpointer= checkpointer)
Tableau 18-1 Propriétés de configuration de l'outil d'invite
| Propriété | Type | Description |
|---|---|---|
| llm | objet | Détails et paramètres de connexion LLM |
| model_id | chaîne | Identifiant du modèle à utiliser (par exemple, "xai.grok-4") |
| fournisseur_modèle | chaîne | Nom du fournisseur pour le modèle LLM (par exemple, "générique") |
| ID_compartiment | chaîne | OCID de compartiment Oracle Cloud Infrastructure (OCI) |
| endpoint | chaîne | URL endpoint du modèle |
| modèle_invite | chaîne | Modèle d'invite utilisé par le LLM, avec des variables au format {{variable}} pour insertion dynamique |
Outils d'invite d'agent de test
Pour tester l'outil indépendamment de l'agent, cliquez sur l'onglet Test et renseignez la valeur de chaque paramètre. L'invite est soumise au LLM que vous avez sélectionné.
Assurez-vous que votre outil d'invite est bien défini et documenté pour améliorer les résultats de votre agent.
Ajout d'un outil d'invite à un agent
Vous pouvez ajouter un outil d'invite à vos agents pour vous permettre de définir des invites paramétrées que vous émettez pour le LLM de votre choix.
- Accédez à votre agent.
- Dans les modèles d'outil, glissez-déplacez un outil d'invite vers votre canevas.
- Dans l'onglet Configuration, sélectionnez le LLM à utiliser et indiquez l'invite du LLM. Cliquez sur Code
pour indiquer la configuration en tant que code JSON. - Fournissez une température pour la réponse sous la forme d'une valeur comprise entre 0,0 et 1,0, où 0,0 fournit une réponse strictement factuelle et 1,0 la réponse la plus créative.
- Cliquez sur Appliquer
. - Indiquez les définitions des paramètres que vous avez définis dans la configuration. Cliquez sur Code pour indiquer la configuration en tant que code JSON.
- Cliquez sur
Appliquer. - Facultatif : cliquez sur l'onglet Test. Indiquez les paramètres de test et cliquez sur Soumettre. Reportez-vous aux résultats du test dans le panneau Résultats du test.
Outil RAG
L'outil RAG émet une requête en langage naturel vers une banque de vecteurs et extrait des documents en fonction de la similarité sémantique entre la requête et les documents stockés.
Remarques :
Une base de connaissances est une condition préalable à la création d'un outil RAG. Pour plus d'informations, reportez-vous à Bases de connaissance.Outils RAG via Visual Flow
En tant que développeur d'agent, l'outil RAG doit fournir des valeurs pour les paramètres suivants :
- Face à l'agent :
- Nom de l'outil : nom descriptif de l'outil qui vous aide, vous et d'autres utilisateurs, à identifier sa fonction.
- Description de l'outil : résumé qui fournit une présentation de l'outil.
- Configuration d'outil:
- Base de connaissances : base de connaissances stockée dans l'un de vos catalogues Oracle AI Data Platform Workbench.
- Base de connaissances : base de connaissances stockée dans l'un de vos catalogues Oracle AI Data Platform Workbench.
L'agent définit la valeur du champ de requête en fonction de sa conversation avec l'utilisateur final. Ce champ de requête prend une requête en langage naturel.
La limite est le nombre de blocs de documents que vous voulez que l'outil récupère à partir de la banque de vecteurs. Cette valeur est définie par le développeur de l'agent et non par l'agent lui-même.
Vous pouvez simuler une requête émise par l'agent en cliquant également sur l'onglet de test de la RAG :
Outils RAG via le code LangGraph
Pour créer un outil RAG dans votre agent via du code, vous devez configurer les mêmes paramètres que le flux visuel. Par exemple, vous définissez les paramètres RAG comme suit :
rag_params = [ { "name" : "query",
"type" : "string",
"description" : "<insert a description>",
"defaultValue" : "<empty>”} ]Vous allez ensuite configurer la RAG :
rag_config = { "catalog": "<catalog>",
"schema": "<schema>",
"knowledgeBase": "<knowledge-base-name>",
"top_k": <number-of-documents-retrieved>,
"llm": {
"model_id" : "<model-name>",
"model_provider" : "<model-provider>",
"compartment_id" : "<your-compartment-OCID>",
"endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" }
}Enfin, vous créez un outil compatible LangGraph avec la fonction utilitaire create_langgraph_tool() à partir d'aideputils :
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>",
description= "<your-tool-description>",
tool_class = "RAGTool",
conf=rag_config,
params=rag_params)
rag_tool = create_langgraph_tool(rag_conf.model_dump())Tableau 18-2 Propriétés de configuration de l'outil RAG
| Propriété | Type | Description |
|---|---|---|
| llm | objet | Détails de connexion LLM |
| catalog | chaîne | Identifiant du catalogue de données |
| schémas | chaîne | Schéma dans le catalogue |
| Base des connaissances | chaîne | Nom ou clé de la base de connaissances à rechercher |
| top_k | entier | Nombre de principaux documents correspondants à extraire |
Agent de test - Outils RAG
Vous pouvez tester l'outil RAG à partir de l'onglet Test après avoir attaché votre agent à un cluster de calcul AI. Pour plus d'informations, reportez-vous à Attachement d'un cluster AI existant à un agent.
Ajout d'un outil RAG à un agent
Vous pouvez ajouter un outil de génération augmentée de récupération (RAG) à vos agents pour permettre à l'agent d'extraire les connaissances externes pertinentes lors de la génération d'une réponse.
- Accédez à votre agent.
- A partir des modèles d'outil, faites glisser un outil RAG vers votre canevas.
- Dans l'onglet Configuration, sélectionnez la base de connaissances à partir de laquelle l'outil RAG extrait les informations et indiquez l'invite de définition des informations à extraire. Cliquez sur Code pour indiquer la configuration en tant que code JSON.
- Cliquez sur Appliquer .
- Indiquez les définitions des paramètres que vous avez définis dans la configuration. Cliquez sur Code pour indiquer la configuration en tant que code JSON.
- Cliquez sur Appliquer.
- Facultatif : cliquez sur l'onglet Test. Indiquez les paramètres de test et cliquez sur Soumettre. Reportez-vous aux résultats du test dans le panneau Résultats du test.
Outil SQL
L'outil SQL permet aux développeurs d'agent d'exécuter des requêtes SQL prédéfinies sur des tables inscrites dans un catalogue Oracle AI Data Platform.
Vous écrivez la requête lors de la conception et définissez les variables d'exécution dont elle a besoin. L'agent fournit des valeurs pour ces variables lorsqu'il appelle l'outil, et les résultats renvoient sous forme de lignes structurées que l'agent peut résumer ou transmettre à un noeud en aval.
L'outil SQL prend en charge deux dialectes de requête. Spark SQL s'exécute sur les tables de catalogue standard stockées dans AI Data Platform et requiert un cluster Spark. Oracle SQL s'exécute sur une base de données externe telle qu'Oracle Autonomous AI Database. Vous choisissez le dialecte par outil et le reste de la configuration est le même pour les deux.
Remarques :
L'outil SQL est destiné aux requêtes en lecture. Un outil standard exécute une instruction SELECT et renvoie des lignes. Le catalogue, le schéma et la requête que vous configurez sont privés de l'outil et ne sont pas exposés à l'agent. Seuls le nom de l'outil, la description et la définition de l'outil AI (les variables d'exécution) sont visibles pour l'agent.Remarques :
L'outil de requête SQL ne démarre pas automatiquement les clusters arrêtés. Par conséquent, le cluster Spark utilisé pour l'outil de requête Spark SQL doit avoir une durée de version. Si le cluster est autorisé à basculer sur un délai d'inactivité, les requêtes SQL Spark cessent de fonctionner en production une fois le cluster arrêté.Requêtes statiques et dynamiques
Une requête statique renvoie exactement ce que vous indiquez, sans décision d'exécution de la part de l'agent. Une requête dynamique inclut des espaces réservés {{variable}} qui indiquent à l'agent que la valeur est définie lors de l'exécution. Pour chaque espace réservé, vous fournissez un nom, un type, une valeur par défaut facultative et une description que l'agent utilise pour choisir la valeur.
SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = 2025
ORDER BY customer_name {{year}} le transforme en requête dynamique que l'agent peut paramétrer : SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = {{year}}
ORDER BY customer_name Lorsque vous ajoutez des espaces réservés, le volet de définition de l'outil AI est renseigné avec chaque variable afin que vous puissiez définir son type, sa valeur par défaut et sa description.
SELECT incident_id, project_id, incident_date, incident_type,
severity, description, workers_involved, days_lost,
root_cause, corrective_action, reported_by, status
FROM safety_incidents
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')Donnez à chaque variable une description claire et une valeur par défaut raisonnable. La description indique à l'agent quelles valeurs sont valides et la valeur par défaut est utilisée lorsque l'agent n'en fournit pas.
Remarques :
Pour les noms d'espace réservé, distinguez les majuscules des minuscules. Un espace réservé écrit en tant que{{SEVERITY}} et un autre en tant que {{severity}} sont traités comme deux variables différentes, sauf si vous utilisez systématiquement des minuscules.
Modification de la configuration en tant que JSON
{
"catalogKey": "construction_data",
"schemaKey": "admin",
"query": "SELECT project_id, project_name, client_name, ...",
"isRowLimitEnabled": null,
"maxRows": null
}
Limites de ligne
Vous pouvez limiter le nombre de lignes renvoyées par l'outil en sélectionnant Nombre maximal de lignes à renvoyer et en saisissant une valeur limite. Les limites de ligne protègent les performances et contrôlent la quantité de données renvoyées à l'agent.
Définissez cette valeur par rapport au modèle que votre agent utilise. Des valeurs plus élevées peuvent entraîner des échecs d'agent lorsque les requêtes renvoient des lignes ou des colonnes larges contenant des valeurs de texte volumineuses. Si vous constatez des erreurs d'agent inattendues, commencez par réduire maxRows.
La limite de lignes est appliquée à la requête SQL elle-même, avant l'exécution de la requête. La plupart des modèles détectent la limite et la font apparaître à l'utilisateur final. Pour une requête statique, la limite renvoie les n premières lignes disponibles.
Remarques :
Si vous ne souhaitez pas que vos limites de ligne apparaissent pour les utilisateurs finaux, insérez les instructions correspondantes à l'agent.Exemples de requête
Vous pouvez voir des exemples de requête et un guide pour écrire des requêtes d'outil SQL à partir du bouton Afficher les exemples et le guide de requête.
Le guide présente différents modèles de requête et fournit différentes recommandations sur les paramètres de requête.
Outils SQL via le code LangGraph
Comme pour le flux visuel, vous commencez à créer un outil SQL pour votre agent via le code LangGraph en créant une requête :
sql_config = { "catalogKey": "adw23ai_phx",
"schemaKey": "gold",
"query": """Select ... from ... limit {{max_number}}""" }
Vous documentez chaque paramètre de la requête SQL dans l'argument params avec un nom, un type, une description et éventuellement une valeur par défaut.
sql_params = [ { "name" : "max_number",
"type" : "string",
"description" : "<your-description>",
"defaultValue" : "<your-default-value>" } ]Enfin, vous créez un outil compatible LangGraph avec la fonction utilitaire create_langgraph_tool() à partir d'aideputils :
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>",
description= "<your-tool-description>",
tool_class = "SQLTool",
conf=sql_config,
params=sql_params)
sql_tool = create_langgraph_tool(sql_conf.model_dump())Tableau 18-3 Propriétés de configuration de l'outil SQL
| Propriété | Type | Description |
|---|---|---|
| Clé de catalogue | chaîne | Identificateur de la connexion au catalogue ou à la base de données |
| clé de schéma | chaîne | Nom de schéma dans le catalogue/la base de données |
| requête | chaîne | Chaîne de requête SQL, peut inclure des espaces réservés dans {{}} |
Outils SQL d'agent de test
L'onglet Test exécute l'outil seul, sans exécuter l'agent complet. Les tests fonctionnent de la même manière pour les deux dialectes. Ouvrez l'onglet Test, indiquez une valeur pour chaque paramètre d'exécution (ou utilisez les valeurs par défaut), puis cliquez sur Soumettre pour exécuter la requête et afficher la réponse.
Remarques :
Le test d'un outil nécessite que votre agent soit associé à un calcul d'IA. Un calcul AI est attaché si le libellé de calcul AI est vert et que le calcul AI sélectionné est à l'état ACTIVE.Référence de commande SQL
Les requêtes d'outil SQL sont des requêtes de lecture créées à partir des clauses SQL standard. Le dialecte Oracle SQL suit Oracle SQL par rapport à la base de données externe. Le dialecte Spark SQL cible les tables de catalogue standard, qui sont des tables Delta Lake. Le catalogue standard exécute actuellement Spark 3.5 avec Delta Lake 3.2.0. La plupart des clauses sont écrites de la même manière dans les deux dialectes, car les deux suivent le code SQL standard. La principale différence est la façon dont chaque dialecte limite le nombre de lignes. Le tableau suivant répertorie les clauses et les mots-clés les plus souvent utilisés dans les requêtes d'outils SQL, avec le formulaire pour chaque dialecte.
| Mot-clé ou clause | Description | Oracle SQL | Spark SQL |
|---|---|---|---|
| SELECT | Choisir les colonnes à renvoyer | SELECT col1, col2 |
|
| DISTINCT | Renvoyer uniquement les lignes uniques | SELECT DISTINCT col |
SELECT DISTINCT col |
| FROM | Nommer la table source | FROM table_name |
FROM table_name |
| WHERE | Filtrer les lignes par condition | WHERE col = value |
WHERE col = value |
| ET OU PAS | Combiner ou annuler des conditions | a AND b OR NOT c |
a AND b OR NOT c |
| IN | Correspond à n'importe quelle valeur d'une liste | col IN (a, b, c) |
col IN (a, b, c) |
| BETWEEN | Correspond à une plage inclusive | col BETWEEN x AND y |
col BETWEEN x AND y |
| LIKE | Correspond à un modèle de texte | col LIKE 'A%' |
col LIKE 'A%' |
| IS NULL | Test des valeurs manquantes | col IS NULL |
col IS NULL |
| ORDER BY | Trier le résultat | ORDER BY col DESC |
ORDER BY col DESC |
| GROUPER PAR | Regrouper les lignes pour l'agrégation | GROUP BY col |
GROUP BY col |
| HAVING | Filtrer les lignes groupées | HAVING COUNT(*) > 1 |
HAVING COUNT(*) > 1 |
| REJOINDRE LE | Combiner les lignes de deux tables | a JOIN b ON a.id = b.id |
a JOIN b ON a.id = b.id |
| AS | Alias d'une colonne ou d'une table | col AS name |
col AS name |
| UNION ALL | Fusion de deux ensembles de résultats | q1 UNION ALL q2 |
q1 UNION ALL q2 |
| CASE | Renvoyer une valeur sous condition | CASE WHEN c THEN x END |
CASE WHEN c THEN x END |
| Agrégats | Synthèse sur plusieurs lignes | COUNT SUM AVG MIN MAX |
COUNT SUM AVG MIN MAX |
| Limite de ligne | Plafonner le nombre d'enregistrements | FETCH FIRST n ROWS ONLY |
LIMIT n |
Remarques :
Normalement, vous n'écrivez pas la limite de ligne vous-même. Le paramètre Max rows to return vous l'applique. Les formulaires FETCH FIRST et LIMIT ne sont utiles que lorsque vous souhaitez définir une limite explicite dans la requête.Pour une grammaire SQL complète et les moteurs de requête derrière chaque dialecte, reportez-vous aux références suivantes :
Spark SQL et Delta Lake (catalogue standard)
- Syntaxe SQL Apache Spark : instructions LMD, syntaxe de requête SQL Spark et d'instruction LMD.
- Delta Lake : Supprime, met à jour et fusionne des tables Opérations DELETE, UPDATE et MERGE sur les tables Delta.
- Delta Lake : commandes de l'utilitaire Table Opérations de l'utilitaire telles que OPTIMIZE et VACUUM.
- Delta Lake : Utiliser le clustering liquide pour les tables Delta Clustering liquide pour la disposition des tables Delta.
Ajouter un outil SQL à un agent
Vous pouvez ajouter un outil SQL à vos agents pour leur permettre d'exécuter des requêtes SQL sur des sources de données structurées dans des catalogues externes inscrits.
- Cliquez sur la poignée de connecteur de votre agent et faites-la glisser pour vous connecter au noeud d'outil.
- Choisissez le dialecte de requête :
- Spark SQL écrit des requêtes sur les catalogues AI Data Platform standard.
- Oracle SQL écrit des requêtes sur des catalogues AI Data Platform externes.
Remarques :
Spark SQL requiert un cluster Spark en cours d'exécution dans votre espace de travail AI Data Platform Workbench.
- Dans la liste déroulante Cluster, sélectionnez un cluster Spark en cours d'exécution. Cliquez sur Créer un cluster pour provisionner un nouveau cluster Spark. Pour obtenir des instructions sur la création d'un cluster, reportez-vous à Création d'un cluster personnalisé.
Remarques :
L'outil de requête SQL ne démarre pas automatiquement les clusters arrêtés. Par conséquent, le cluster Spark utilisé pour l'outil de requête Spark SQL doit avoir une durée de version. Si le cluster est autorisé à basculer sur un délai d'inactivité, les requêtes SQL Spark cessent de fonctionner en production une fois le cluster arrêté.
- Sous Parcourir le catalogue, utilisez le champ de recherche pour localiser un catalogue par son nom ou cliquez sur le gestionnaire de catalogues pour localiser le catalogue.
- Dans le champ Requête, entrez votre requête. Cliquez sur Afficher les exemples et le guide de requête pour ouvrir un panneau contenant des modèles prêts à l'emploi que vous pouvez copier ou adapter.
- Dans le panneau Définition de l'outil AI, définissez le type, la valeur par défaut et la description des variables définies dans votre requête.
- Facultatif : cliquez sur l'onglet Test. Indiquez les paramètres de test et cliquez sur Soumettre. Reportez-vous aux résultats du test dans le panneau Résultats du test.