22 Agents AI

Ce chapitre fournit des informations sur la création, le test, le déploiement et la surveillance d'agents dans votre espace de travail.

Les agents sont des applications agentiques de bout en bout. Les agents sont définis via un graphique d'étapes représenté par des noeuds de différents types (déclencheurs, agents, garde-corps ou outils). Les agents peuvent être définis via un générateur de flux visuel sans code et via du code via des bibliothèques tierces, telles que LangGraph.

Oracle AI Data Platform Workbench propose plusieurs modèles d'outil qui peuvent être configurés pour accéder à vos données et répondre à vos cas d'utilisation. Les outils pris en charge sont :

• Outil personnalisé : l'outil 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. L'agent appelle votre code en tant qu'outil, avec les paramètres fournis par le LLM lors de l'exécution.
• HTTP : l'outil de demande HTTP permet à votre 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.
• 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.
• Serveur MCP distant : les développeurs d'agent peuvent connecter leurs agents à des serveurs MCP (Remote Model Context Protocol) à l'aide de l'outil Serveur MCP distant.
• 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 (23ai 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 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.

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é.

La création d'agents dans AI Data Platform Workbench génère un fichier d'artefact d'agent (.aflow) dans le dossier d'espace de travail que vous sélectionnez. Ce fichier ne peut pas être modifié.

Systèmes multi-agents et modèles de superviseur

Un système multi-agent est une conception d'application AI dans laquelle une demande utilisateur est traitée par plusieurs agents coopérants au lieu d'un agent polyvalent.

Chaque agent a son propre rôle, des instructions, une configuration de modèle, une stratégie de mémoire et des outils autorisés. Le flux définit la façon dont la demande se déplace entre ces agents et la façon dont la réponse finale est produite.

Cette conception est utile lorsqu'un flux de travail se sépare naturellement en responsabilités spécialisées. Par exemple, un agent peut extraire des données, un autre peut appeler une API, un autre peut résumer les résultats et un superviseur peut décider quel spécialiste utiliser et combiner les résultats en une seule réponse.

Remarques :

En tant que principe de conception, il est préférable de commencer par la plus petite conception d'agent qui répond aux exigences. Ajoutez plusieurs agents lorsque la séparation des préoccupations améliore davantage la fiabilité, la sécurité, la maintenabilité ou l'observabilité qu'elle n'augmente les coûts et la complexité.

Avantages des systèmes multi-agents

Les systèmes multi-agents sont les mieux adaptés pour :

• Spécialisation : attribuez à chaque agent un travail, une invite et un ensemble d'outils ciblés au lieu d'un bloc d'instructions bondé.
• Gamme et décomposition : permet à un superviseur d'interpréter la demande, de la diviser en sous-tâches et de choisir le spécialiste approprié pour chaque sous-tâche.
• Isolement des outils et des données : expose les outils sensibles ou à fort impact uniquement aux agents responsables de leur utilisation.
• Gouvernance et dépannage : facilitent l'inspection des transferts, de la propriété des outils, des paramètres de mémoire et des points d'échec.

Quand choisir des conceptions à agent unique ou à agent multiple

Un agent unique avec plus d'outils est souvent la bonne première conception. Il est plus simple à tester, moins coûteux à exécuter et plus facile à raisonner lorsque la tâche a un objectif clair et un modèle d'autorisation. Utilisez une conception multi-agent lorsque le workflow bénéficie de rôles explicites, d'un accès limité aux outils ou d'un superviseur capable de coordonner plusieurs sorties spécialisées.

Question de conception	Utiliser des agents uniques lorsque...	Utiliser des multi-agents lorsque...
Forme de tâche	La demande a un objectif principal et un seuil de réponse.	La demande doit être décomposée, routée, vérifiée ou synthétisée dans toutes les spécialités.
Outils et données	Le même jeu d'instructions et le même modèle d'autorisation peuvent régir tous les outils en toute sécurité	Les différents agents ont besoin d'outils, de sources de données ou de limites d'accès différents.
Instructions	L'invite reste claire, même avec toutes les règles métier et toutes les instructions relatives aux outils en un seul endroit.	Les instructions sont plus faciles à gérer en tant qu'invites plus petites et spécifiques au rôle.
Coût et latence	Vous voulez que le chemin le plus court du message utilisateur réponde.	Les avantages en matière de fiabilité, de gouvernance ou de maintenabilité justifient une orchestration supplémentaire.
Dépannage	Les échecs sont simples à déboguer en une seule trace.	Vous avez besoin de transferts explicites, d'un isolement par état et d'une propriété plus claire pour chaque étape.

Modèle pris en charge : orchestrateur/superviseur

L'expérience canevas actuelle prend en charge le modèle orchestrateur/superviseur. Dans ce modèle, le déclencheur de discussion reçoit le message utilisateur, les garde-corps facultatifs évaluent l'entrée et un agent superviseur agit en tant qu'orchestrateur pour le reste du flux.

Le superviseur doit se concentrer sur la planification, l'acheminement, la délégation et la synthèse des réponses finales. Il détermine l'agent exécuteur qui doit gérer une tâche, envoie à l'exécuteur une instruction de portée, examine le résultat, puis délègue une autre étape ou renvoie la réponse finale. Les agents exécutifs doivent être des spécialistes plus étroits : ils effectuent le travail assigné, utilisent les outils qui leur sont associés et renvoient des résultats utiles au superviseur.

A propos du canevas Visual Flow

Un agent est assemblé en faisant glisser des nœuds et des modèles d'outil de la palette de gauche vers le canevas, puis en connectant les nœuds dans l'ordre dans lequel la demande doit voyager.

La sélection d'un noeud ouvre un panneau de configuration en bas de l'écran.

Elément de canevas	Description
Déclencheur de discussion	Point d'entrée pour un message utilisateur. Dans la capture d'écran, ce noeud est étiqueté Message et se trouve généralement en haut du flux. Un noeud de déclencheur de discussion peut être connecté à un agent, un agent de superviseur ou un noeud de garde-fous. Un seul déclencheur de discussion est autorisé par canevas.
Glissières de sécurité	Couche de sécurité et de politique facultative placée avant ou après le travail du modèle. Les stratégies de garde-corps comprennent les informations d'identification personnelle, la modération du contenu et la détection d'injection rapide. Un noeud de garde-corps peut filtrer le trafic entre un déclencheur de discussion et un noeud d'agent, entre un superviseur et des agents exécutifs, ou entre des noeuds d'agent et d'outil. Nous recommandons un noeud de garde-fous unique entre le déclencheur de discussion et le noeud d'agent.
Agent superviseur	L'orchestrateur. Il reçoit la demande de l'utilisateur, décide quel agent exécuteur ou outil doit gérer chaque tâche et coordonne la réponse finale. Un seul agent superviseur est autorisé dans un canevas.
Agent	Un agent exécuteur. Chaque exécuteur doit avoir une spécialité claire, telle que la récupération de données, la consultation d'API, la synthèse ou la réponse aux questions de document. Utilisez un agent/agent exécuteur pour un système à agent unique.
Modèles d'outils	Fonctionnalités réutilisables pouvant être associées à un exécuteur individuel ou à un agent superviseur. Les modèles d'outil incluent SQL, RAG, Prompt, HTTP, Serveur MCP distant et Outil personnalisé.
Développement / Aire de jeux	Sélecteur de mode au-dessus du canevas. Le développement est utilisé lors de la modification du système agénétique ; Playground est utilisé pour lancer des sessions de test et inspecter le comportement de l'agent. Playground de test nécessite qu'un calcul d'IA soit attaché à votre agent.
Contrôle du zoom	Sélecteur de zoom de canevas. Les captures d'écran montrent des niveaux de zoom de 60 % et 90 %.

Créer un Agent

Vous pouvez créer un agent dans un espace de travail pour lequel vous disposez de l'autorisation Gérer.

1. Sur la page d'accueil, accédez à votre espace de travail.
2. Cliquez sur Flux d'agent dans le panneau de navigation de gauche.
3. Cliquez sur Créer un agent ou sur Créer en haut à droite.
   
   

   

   
   
4. Indiquez le nom et la description de l'agent.
5. Pour Mode de rédaction de flux d'agent, sélectionnez Générateur visuel.
   
   

   

   
   
6. Facultatif : dans le menu déroulant Calcul AI, sélectionnez le calcul à utiliser pour l'agent.
7. Cliquez sur Créer. Commencez à créer votre agent en faisant glisser un noeud de la palette vers le canevas.

   Remarques :

   Démarrez votre premier build d'agent simple : un déclencheur de discussion, un agent exécuteur. Ajoutez de la complexité après une exécution réussie de votre première construction, comme des garde-corps, des outils supplémentaires ou même une conception de système multi-agents.

Ajouter un déclencheur de discussion et un agent au canevas Visual Builder

La première étape après la création d'un agent avec Visual Builder doit consister à ajouter un déclencheur de discussion et un agent superviseur.

Le déclencheur reçoit le message utilisateur. Le superviseur interprète la demande, planifie le travail et délègue les tâches aux agents exécutifs ou aux outils. Vous pouvez faire glisser des noeuds dans le canevas, les configurer et les connecter ultérieurement.

1. Accédez à votre agent dans votre espace de travail.
2. Cliquez sur un déclencheur de discussion et faites-le glisser de la palette vers le canevas. Le noeud apparaît sur le canevas sous forme de message.
3. Cliquez sur un agent superviseur et faites-le glisser vers le canevas.
   
   

   

   
   
4. Cliquez sur le descripteur de connecteur du noeud Déclencheur de discussion et faites-le glisser pour le connecter au noeud Agent.

Le badge Agent superviseur affiche le nombre d'agents et d'outils connectés. Dans une nouvelle version, l'agent superviseur affiche : Agents (0) Outils (0).

Configurer un agent superviseur

Vous devez configurer un agent de superviseur ajouté au canevas Visual Builder avec des instructions décrivant le rôle de superviseur.

Vous configurez un agent superviseur avec les champs suivants.

Champ	Configuration
Nom de l'agent	Indiquez un nom descriptif pour l'agent superviseur. Un bon nom descriptif sera utile lors du débogage du comportement du système via des traces et des journaux.
Description d'agent	Fournissez une description de l'objectif, du rôle et du comportement général de l'agent. Utile pour la documentation.
Région	Choisissez la région dans laquelle le modèle OCI Generative AI utilisé par l'agent superviseur est hébergé. Reportez-vous à Modèles d'IA générative par région.
Modèle	Choisissez le modèle de service OCI Generative AI utilisé par le superviseur. La liste déroulante répertorie les modèles disponibles dans la région que vous avez sélectionnée.
Instructions de l'agent	Décrire le rôle de superviseur, les règles d'acheminement, la stratégie de délégation, les attentes en matière d'utilisation des outils et le format de réponse finale.

1. Accédez à l'agent dans votre espace de travail.
2. Cliquez sur le noeud Agent superviseur sur le canevas.
3. Indiquez un nom et une description détaillés pour votre agent superviseur.
4. Entrez la région et le modèle pour le modèle de service OCI Generative AI utilisé par le superviseur.
5. Fournissez les instructions de l'agent pour votre agent superviseur.

Instructions suggérées pour le superviseur

Vous devez utiliser le champ Instructions d'un agent superviseur pour que ce dernier soit responsable de l'orchestration et non de toutes les tâches.

Gardez les instructions concrètes pour que les décisions de routage soient prévisibles. Pour obtenir un exemple d'ensemble d'instructions du superviseur, reportez-vous aux sections suivantes :

You are the supervisor for a multi-agent system.

Responsibilities:
- Understand the user's request and break it into subtasks.
- Select the most appropriate executor agent or tool for each subtask.
- Do not perform specialist work yourself when an executor agent is available.
- Ask for clarification only when required information is missing.
- Combine executor outputs into a concise final answer.
- Mention important assumptions, limits, or failed tool calls in the final answer.

Routing rules:
- Use the SQL agent for structured data questions.
- Use the HTTP agent/tool for external API lookups.
- Use the RAG agent/tool for document or knowledge-base questions.
- Use the prompt tool for reusable prompt-only transformations.

Configurer l'isolement de la mémoire et de l'état de l'agent du superviseur

L'onglet Mémoire d'un agent superviseur contrôle la quantité de conversation et l'historique de sortie d'outil disponibles pour le superviseur et la quantité de contexte partagée avec les agents exécutifs.

Vous configurez l'état de mémoire et d'isolement pour votre agent superviseur à l'aide des champs suivants.

Champ	Configuration
Activer la mémoire de l'agent	Activer lorsque les utilisateurs ont besoin d'une continuité multitour. Désactiver pour les tâches isolées à usage unique. Ce champ ne peut pas être désactivé pour les agents superviseur.
Limiter l'historique des conversations	Activer pour tronquer la fenêtre de contexte LLM après l'atteinte de la limite spécifiée. Désactiver pour afficher l'historique complet.
Configuration de la troncature	Si l'option Limiter l'historique des conversations est activée, utilisez ce champ pour définir les conditions de troncation de la fenêtre de contexte. Les options disponibles sont les suivantes : Conserver les N derniers messages Budget du jeton Les deux
Limites de message maximum et budget de jeton	L'une de ces options ou les deux sont affichées, en fonction de votre choix pour Configuration de la troncature. Les valeurs par défaut sont 20 messages et 5000 jetons. Nous recommandons de commencer par des valeurs modérées et de les ajuster au besoin.
Isolation d'état pour les agents exécutifs	Sélectionnez Sans conservation de statut, Privé ou Partagé. Sans conservation de statut : chaque agent exécuteur ne voit que la tâche affectée par le superviseur. Aucun historique n'est reporté entre les appels. Sélectionnez cette option si vous souhaitez bénéficier de l'isolation la plus forte et du contexte d'agent croisé le moins important. Privé : chaque agent exécuteur ne voit que ses propres interactions passées. Il ne peut pas voir d'autres agents exécutifs de la conversation utilisateur d'origine. Sélectionnez cette option si l'exécuteur a besoin d'une continuité entre ses propres tâches, mais ne doit pas partager le contexte avec d'autres agents. Partagé : les agents exécutifs peuvent voir l'historique complet des conversations entre les agents et les utilisateurs. Tous les agents travaillent à partir d'un contexte partagé. Sélectionnez cette option si vous avez besoin d'un large partage de contexte et que vous avez examiné les risques liés à la confidentialité et à l'injection rapide.

1. Accédez à l'agent dans votre espace de travail.
2. Cliquez sur le noeud Agent superviseur sur le canevas.
3. Cliquez sur l'onglet Mémoire.
4. Choisissez d'activer ou non Limiter l'historique des conversations. Sélectionnez une configuration de troncature et définissez des limites, si elle est activée.
5. Choisissez une option pour Isolement d'état pour les agents d'exécuteur.

Onglet Paramètres des modèles

L'onglet Paramètres de modèle vous permet de configurer les paramètres propres au modèle qui sont disponibles pour le modèle sélectionné.

Les paramètres de modèle peuvent être configurés séparément pour les agents superviseur et exécuteur. Les paramètres que vous pouvez utiliser incluent la température, le K supérieur, le P supérieur et la pénalité de fréquence.

Remarques :

Seul un sous-ensemble de modèles expose des paramètres configurables. En outre, les paramètres varient selon les familles de modèles.

Ajouter des garde-corps à un agent

Vous pouvez ajouter des couches de protection supplémentaires à vos agents en ajoutant des noeuds de garde-corps à votre canevas.

Par défaut, aucun garde-corps n'est appliqué à vos systèmes agénétiques au-delà de ce que le fournisseur de modèles sélectionné offre prêt à l'emploi pour ses modèles. Des garde-corps peuvent être placés entre le déclencheur de discussion et l'agent superviseur afin que les stratégies soient appliquées avant qu'une demande n'atteigne l'agent superviseur et avant que l'agent superviseur ne renvoie une réponse à l'appelant.

Garde-fou	options	Utilisation
Informations d'identification personnelle (PII)	Onglets Entrée et Sortie Cases à cocher pour Personne, Adresse, Numéro de téléphone, E-mail	A utiliser lorsque le flux doit bloquer ou masquer les données personnelles sensibles avant ou après le traitement du modèle.
Prévention de la modération du contenu	Lignes d'entrée et de sortie avec options Bloquer, Informer et Autoriser.	Permet de définir comment le flux gère le contenu haineux, sexuel, violent, toxique, péjoratif ou harcelant.
Détection d'injection d'invite	Ligne d'entrée avec options Bloquer et Autoriser.	Permet de réduire les risques que des instructions malveillantes remplacent les instructions du système ou de l'agent.

Pour plus d'informations sur les paramètres de garde-corps, reportez-vous à la section Guardrails.

1. Accédez à l'agent dans votre espace de travail.
2. Faites glisser un noeud Guardrails de votre palette vers votre canevas. Placez-le entre le noeud Déclencheur de discussion et le noeud Agent superviseur.
3. Supprimez la connexion entre le déclencheur de discussion et l'agent du superviseur en survolant la connexion et en cliquant sur le X rouge.
   
   

   

   
   
4. Cliquez sur la poignée du connecteur du déclencheur de discussion et faites-la glisser vers le noeud Guardrail. Ensuite, cliquez sur le descripteur de connecteur du noeud de garde-corps et faites-le glisser vers l'agent superviseur.
5. Cliquez sur le noeud Guardrail pour ouvrir la page Configuration.
6. Configurez les garde-corps pour sélectionner l'action souhaitée pour les vérifications d'entrée et de sortie.

Ajouter des outils et des agents d'exécuteur à un agent

Vous pouvez ajouter des agents exécutifs aux outils pour effectuer un travail spécialisé pour l'agent superviseur.

Dans l'exemple ci-dessous, l'agent superviseur délègue à AGENT_1 et AGENT_2. AGENT_1 est connecté aux outils SQL_1 et HTTP_1.

1. Accédez à l'agent dans votre espace de travail.
2. Faites glisser un noeud d'agent de la palette vers le canevas. Les noeuds d'agent doivent être placés sous un agent supérieur.
3. Faites glisser Tools de la palette vers votre canevas.
4. Cliquez et faites glisser la poignée de connecteur sur votre agent superviseur pour vous connecter aux noeuds d'agent.
5. Cliquez sur la poignée de connecteur de vos agents et faites-la glisser pour vous connecter aux noeuds d'outil.

Configuration de l'agent d'exécuteur

Les noeuds d'agent peuvent être configurés en modifiant les paramètres de leurs onglets Configuration, Mémoire et Modèle pour vous aider à définir l'objectif de chaque agent.

Les agents doivent être configurés de manière étroite, en fonction d'une fonction et d'un objectif spécifiques, afin que l'agent superviseur puisse acheminer le travail de manière fiable.

Tableau 22-1 Onglet Configuration de l'agent

Champ	Configuration
Nom de l'agent	La meilleure pratique consiste à nommer chaque agent exécuteur en fonction de sa spécialité, telle que SQL_AGENT, DOCUMENT_AGENT, API_AGENT ou SUMMARY_AGENT. Le nom de chaque agent exécuteur est visible par l'agent superviseur. Utilisez donc des noms descriptifs.
Description d'agent	Fournissez une description détaillée de chaque agent exécuteur. La description de chaque agent exécuteur est visible par l'agent superviseur.
Région	Choisissez la région dans laquelle le modèle OCI Generative AI utilisé par l'agent est hébergé. Reportez-vous à Modèles d'IA générative par région.
Modèle	Choisissez le modèle de service OCI Generative AI utilisé par l'agent. Le menu déroulant répertorie les modèles disponibles dans la région que vous avez sélectionnée. Sélectionnez un modèle adapté à la tâche de l'exécuteur. Les agents exécutifs n'ont pas besoin d'utiliser le même modèle que l'agent superviseur.
Instructions de l'agent	Décrivez exactement ce que l'exécuteur doit faire, quels outils il peut utiliser et quelle structure de sortie il doit renvoyer.

Onglet Mémoire de l'agent exécuteur

Dans le cas d'agents exécutifs connectés à un agent superviseur, la mémoire des exécuteurs est configurée dans le noeud superviseur et appliquée à tous les agents exécutifs.

Champ	Configuration
Activer la mémoire de l'agent	Activer lorsque les utilisateurs ont besoin d'une continuité multitour. Désactiver pour les tâches isolées à usage unique.
Limiter l'historique des conversations	Activer pour tronquer la fenêtre de contexte LLM après l'atteinte de la limite spécifiée. Désactiver pour afficher l'historique complet.
Configuration de la troncature	Si l'option Limiter l'historique des conversations est activée, utilisez ce champ pour définir les conditions de troncation de la fenêtre de contexte. Les options disponibles sont les suivantes : Conserver les N derniers messages Budget du jeton Les deux
Limites de message maximum et budget de jeton	L'une de ces options ou les deux sont affichées, en fonction de votre choix pour Configuration de la troncature. Les valeurs par défaut sont 20 messages et 5000 jetons. Nous recommandons de commencer par des valeurs modérées et de les ajuster au besoin.
Isolation d'état pour les agents exécutifs	Sélectionnez Sans conservation de statut, Privé ou Partagé. Sans conservation de statut : chaque agent exécuteur ne voit que la tâche affectée par le superviseur. Aucun historique n'est reporté entre les appels. Sélectionnez cette option si vous souhaitez bénéficier de l'isolation la plus forte et du contexte d'agent croisé le moins important. Privé : chaque agent exécuteur ne voit que ses propres interactions passées. Il ne peut pas voir d'autres agents exécutifs de la conversation utilisateur d'origine. Sélectionnez cette option si l'exécuteur a besoin d'une continuité entre ses propres tâches, mais ne doit pas partager le contexte avec d'autres agents. Partagé : les agents exécutifs peuvent voir l'historique complet des conversations entre les agents et les utilisateurs. Tous les agents travaillent à partir d'un contexte partagé. Sélectionnez cette option si vous avez besoin d'un large partage de contexte et que vous avez examiné les risques liés à la confidentialité et à l'injection rapide.

Onglet Paramètres de modèle de l'agent exécuteur

L'onglet Paramètres de modèle vous permet de configurer les paramètres propres au modèle qui sont disponibles pour le modèle sélectionné.

Remarques :

Seul un sous-ensemble de modèles expose des paramètres configurables. Les paramètres varient également entre les familles de modèles.

Des exemples de paramètres incluent la température, le top K, le top P et la pénalité de fréquence. Les paramètres de modèle peuvent être configurés séparément pour les agents superviseur et exécuteur.

Instructions de l'exécuteur suggérées

You are the SQL executor agent.

Responsibilities:
- Translate the supervisor's task into safe SQL tool usage.
- Use only the SQL tools attached to this agent.
- Return a concise answer plus any important query assumptions.
- Do not invent data. If the tool cannot answer, say what is missing.
- Return structured output with: answer, evidence, assumptions, and follow_up_needed.

Liste de contrôle pour les agents via Visual Builder

Utilisez cette liste pour vous assurer que vous avez inclus et configuré tous les composants nécessaires pour un agent créé à l'aide de Visual Builder.

Créer une liste de contrôle

• L'agent a exactement un point d'entrée attendu : Déclencheur de discussion / Message.
• Les garde-corps sont connectés dans la position prévue et activés si nécessaire. Nous recommandons d'insérer des garde-corps entre le message de déclenchement et l'agent.
• L'agent superviseur dispose d'une région, d'un modèle et d'instructions d'orchestration sélectionnés. Pareil pour les agents exécutifs.
• Configurez la mémoire du système multi-agent dans l'onglet Mémoire de l'agent superviseur. Sélectionnez l'isolement de l'état de l'exécuteur correspondant aux exigences de confidentialité et de continuité.
• Chaque agent exécuteur a une spécialité claire et des instructions étroites.
• Chaque outil est associé uniquement à l'agent qui doit l'utiliser.
• Aucun noeud n'est déconnecté.
• Un calcul d'IA est associé au système agénétique pour tester des outils individuels et pour exécuter l'expérience Playground.

Tableau 22-2 Questions communes

Problème	Cause probable	Action suggérée
Le superviseur n'appelle pas d'exécuteur	Les instructions du superviseur sont trop vagues ou aucun exécuteur n'est connecté.	Ajoutez des règles de routage explicites et vérifiez que le noeud d'exécuteur est connecté au superviseur.
L'exécuteur renvoie des réponses générales ou hors sujet	Les instructions d'exécuteur sont trop générales.	Affinez le rôle de l'exécuteur et définissez la structure de sortie requise.
L'outil n'est pas utilisé	L'outil est déconnecté ou connecté au mauvais agent.	Vérifiez la connexion à l'outil et le badge du nombre d'outils de l'agent.
Garde-corps ne tire pas	La section Guardrail est configurée mais n'est pas activée.	Ouvrez le noeud guadrails et vérifiez que la bascule de section est activée.
Fuites de contexte entre les agents	L'isolement de l'état est défini sur Partagé ou la mémoire est plus large que prévu.	Utilisez l'isolement privé ou sans état pour une séparation plus stricte.
Les questions de suivi perdent du contexte	La mémoire est désactivée ou la troncation est trop agressive.	Activez la mémoire et réglez la limite maximale de messages.

L'agent parcourt le code

Vous pouvez utiliser votre propre base de code LangGraph pour les agents d'IA dans Oracle AI Data Platform Workbench ou créer un nouvel agent LangGraph directement sur la plate-forme via l'expérience de codage d'agent.

Vous pouvez utiliser la bibliothèque Python de l'utilitaire AI Data Platform Workbench aidputils pour configurer votre modèle de base et importer des outils système vers votre agent. Pour consulter la référence de l'API aidputils, reportez-vous à API Aidp-utils pour Oracle AI Data Platform Workbench.

Vous créez un agent via du code en téléchargeant un fichier de code existant ou en créant des fichiers de code directement dans l'agent via l'éditeur en ligne.

L'éditeur de code en ligne dans les agents prend en charge les types de fichier de code suivants :

• Python (.py)
• JSON
• TXT
• CSV
• PSV
• SH (Affichage)
• Dossier

Vous pouvez afficher et parcourir les fichiers de code disponibles en cliquant sur la liste déroulante du sélecteur de fichiers.

Fichiers d'entrée et de dépendance

Les fichiers d'entrée sont des fichiers de code qui ont la classe avec les méthodes de configuration et d'appel attendues pour un agent défini en tant que code. Oracle AI Data Platform Workbench exige que vous définissiez un fichier d'entrée pour les agents via du code.

Les fichiers de dépendance sont des fichiers qui incluent des bibliothèques tierces requises par votre agent, définies en tant que code. Les fichiers de dépendance sont généralement des fichiers requirements.txt qui contiennent la liste des bibliothèques tierces requises.

Remarques :

Les bibliothèques tierces sont installées lorsque vous testez votre code dans l'éditeur en cliquant sur le bouton Play ou lorsque vous testez l'agent via l'onglet Test. Nous vous recommandons d'installer des bibliothèques tierces en testant d'abord le code. Les erreurs lors de l'installation des bibliothèques sont affichées dans la cellule de sortie.

Classe d'agent

AgentBasic est une classe de modèle permettant de configurer et d'appeler un agent conversationnel simple à l'aide d'un workflow LangGraph avec conservation de statut. Il démontre la structure requise pour le développement minimal d'agents avec deux méthodes principales :

• setup() : initialise le workflow d'agent et définit le graphique.
• invoke(user_query, **kwargs) : exécute l'agent sur un message utilisateur et renvoie la réponse.

Il peut être exécuté et testé directement à l'aide d'une fonction main() avant l'intégration dans un système plus grand.

Définition

class AgentBasic:
    def __init__(self) -> None:
        self.graph = None
    def setup(self) -> None:
        self.graph = StateGraph(MessagesState)
        self.graph.add_node(mock_llm)
        self.graph.add_edge(START, "mock_llm")
        self.graph.add_edge("mock_llm", END)
        self.graph = self.graph.compile()
        system_prompt = "Be a helpful assistant."
    async def invoke(self, user_query: str, **kwargs):
        user_message = HumanMessage(content=user_query)
        messages = {"messages": [dict(user_message)]}
        try:
            return self.graph.invoke(messages)
        except Exception as e:
            import traceback
            logger.error(f"Exception while calling invoke {e}", exc_info=True)
            print("Stack trace:\n", traceback.format_exc()) 

Appel de test

Cet appel de test est idéal pour les tests fonctionnels initiaux.

Remarques :

Incluez un point d'entrée principal pour les tests autonomes.

import asyncio

async def main():
test_agent = AgentBasic()
test_agent.setup()
result = await test_agent.invoke("Hi there")
print("Agent response:", result)
if __name__ == "__main__":
   asyncio.run(main())

Fonctionnement:

• Le script crée un agent, le configure et envoie un exemple de message utilisateur.
• L'agent répond ({"messages" : [{"role" : "ai", "content" : "hello world"}]} dans cet exemple).

Guide d'utilisation

Créez une classe d'agent avec les méthodes Setup et Invoke.

configuration()	Initialise le workflow de l'agent	agent.setup()
appel()	Exécute l'agent avec un message utilisateur	wait agent.invoke("Votre question")

• Asynchrone : invoke() est une méthode asynchrone. Utilisez-la avec await ou exécutez une boucle asynchrone.
• Test : la protection main() incluse (if __name__ == "__main__":) facilite le test de l'agent avant le déploiement.

Créer un agent via du code par téléchargement

Vous pouvez créer votre application d'agent de bout en bout avec du code existant en téléchargeant votre base de code LangGraph.

Oracle AI Data Platform Workbench prend en charge LangGraph version 1.0.1.

Remarques :

Vous pouvez télécharger des fichiers et des dossiers individuels jusqu'à un maximum de 500 fichiers, chaque fichier peut avoir une taille maximale de 500 Mo. Le téléchargement est limité à une taille totale de 5 Go.

1. Accédez à votre agent dans votre espace de travail. Cliquez sur le nom d'agent.
2. Cliquez sur Charger.
   
   

   

   
   
3. Faites glisser et déposez un fichier dans le volet ou cliquez sur ce bouton pour sélectionner un fichier.
4. Cliquez sur Charger.

Créer un agent via du code en créant un nouveau code

Vous pouvez créer une application d'agent de bout en bout avec du code existant en créant du code directement dans l'agent via l'éditeur de code.

L'éditeur de code prend en charge les types de fichier suivants :

• Python (.py)
• JSON
• TXT
• CSV
• PSV
• SH (Commande minimale)
• Dossiers

1. Accédez à votre agent dans votre espace de travail. Cliquez sur le nom d'agent.
2. Cliquez sur Ajouter un fichier.
   
   

   

   
   
3. Entrez le nom du fichier de code.
4. Sélectionnez un modèle de fichier dans la liste déroulante.
5. Cliquez sur Créer.

Définition d'un fichier d'entrée pour les agents via du code

Votre agent AI via du code nécessite un fichier d'entrée contenant la classe, la configuration et les méthodes d'appel requises pour votre agent.

1. Accédez à votre agent dans votre espace de travail. Cliquez sur le nom d'agent.
2. Dans l'onglet Editeur de code, localisez le fichier d'entrée dans le volet de navigation de gauche. Si le fichier n'existe pas, vous pouvez le télécharger vers le serveur en cliquant sur Télécharger vers le serveur ou le créer en cliquant sur Ajouter un nouveau fichier.
3. Cliquez avec le bouton droit de la souris sur le fichier d'entrée et cliquez sur Définir le fichier d'entrée. Vous pouvez également sélectionner le fichier et cliquer sur le bouton Définir le fichier d'entrée en haut à droite de l'éditeur de code.
   
   

   

   
   

Définition d'un fichier de dépendance pour les agents via du code

Vous devez définir un fichier de dépendance pour les flux d'agents via du code qui contient les bibliothèques tierces dont votre code dépend.

1. Accédez à votre agent dans votre espace de travail. Cliquez sur le nom d'agent.
2. Dans l'onglet Editeur de code, localisez le fichier de dépendance dans le panneau de navigation de gauche, généralement requirements.txt. Si le fichier n'existe pas, vous pouvez le télécharger vers le serveur en cliquant sur Télécharger vers le serveur ou le créer en cliquant sur Ajouter un nouveau fichier.
3. Cliquez avec le bouton droit de la souris sur le fichier de dépendances et cliquez sur Définir la dépendance. Vous pouvez également sélectionner le fichier et cliquer sur le bouton Définir le fichier de dépendances en haut à droite de l'éditeur de code.
   
   

   

   
   

Code agent de test

Vous pouvez tester le code utilisé pour votre agent à partir de l'onglet Test pour valider et déboguer le code.

Vous devez avoir un calcul d'IA attaché à votre agent pour effectuer le test.

1. Accédez à votre agent dans votre espace de travail. Cliquez sur le nom d'agent.
2. Cliquez sur l'onglet Playground.
   
   

   

   
   
3. Cliquez sur Lancer pour tester le fichier de code sélectionné.
   
   

   

   
   

Dans la moitié inférieure de la fenêtre de l'éditeur de code, une cellule de sortie affiche les sorties des instructions print ou logging dans votre code. Les erreurs sont également affichées dans la cellule de sortie.

Compétences des agents en matière de codage

Les compétences d'agent permettent à un agent de repérer et d'utiliser des instructions spécifiques aux tâches, des fichiers de référence, des modèles, des ressources et des scripts exécutables facultatifs sans coder en dur cette connaissance de domaine dans les instructions de l'agent.

Une brique est stockée en tant que dossier dans votre base de code d'agent. Chaque brique a un fichier SKILL.md requis qui décrit ce que fait la brique et comment l'agent doit l'utiliser. Une brique peut également inclure des fichiers de prise en charge tels que des schémas, des exemples, des invites, des modèles, des ressources ou des scripts.

Pour plus d'informations, reportez-vous à Présentation des briques d'agent.

Les compétences des agents soutiennent un modèle de divulgation progressive :

1. L'agent découvre qu'une brique existe.
2. L'agent active la brique uniquement lorsqu'elle est pertinente.
3. L'agent charge des fichiers supplémentaires à partir du dossier de brique uniquement si nécessaire.
4. L'agent peut exécuter un point d'entrée de brique déclaré explicitement, si la brique l'autorise.

Quand utiliser les compétences des agents

Vous devez utiliser Skills lorsque vous souhaitez packager des fonctionnalités d'agent réutilisables telles que :

• Instructions propres au domaine
• Workflows de codage ou d'analyse de données
• Conseils de génération SQL
• Livres de référence sur les processus métier
• Modèles de fichier
• Références du schéma
• Scripts réutilisables pour des calculs, des transformations ou des recherches sécurisés

Les compétences sont utiles lorsque l'agent doit avoir accès à des connaissances spécialisées et réutilisables, mais que vous ne voulez pas placer toutes ces connaissances directement dans l'invite de l'agent.

Fonctionnement des compétences à l'exécution

Lors de l'exécution, l'application hôte détermine les répertoires de brique disponibles, tels que les dossiers de brique de niveau projet et utilisateur. La plate-forme charge les métadonnées de chaque brique à partir de SKILL.md et crée un catalogue associé à un nom de brique.

L'agent peut ensuite utiliser des outils liés aux compétences :

Outil	Description
activate_skill(name)	Charge les instructions de compétence de SKILL.md.
list_skill_files(name, path)	Répertorie les fichiers disponibles dans un dossier de brique.
load_skill_file(name, path)	Charge un fichier de support à partir du dossier de compétences.
run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds)	Exécute un point d'entrée Python déclaré explicitement, si la brique l'autorise.

Certains environnements peuvent également intégrer un récapitulatif des compétences disponibles directement dans l'invite système. Dans cette configuration, l'agent peut repérer les briques disponibles à partir de l'invite, puis utiliser activate_skill lorsqu'il a besoin des instructions complètes.

Structure du dossier de compétences

Une brique utilise une présentation de dossier de type Compétences d'agent :

<skills_dir>/
	some-skill/
		SKILL.md
		references/
		...
		scripts/
		...
		assets/
		...

Seul SKILL.md est requis. Les autres dossiers sont facultatifs.

Fichier ou dossier	Obligatoire	Description
SKILL.md	Oui	Principales métadonnées et instructions relatives aux compétences.
references/	No	Documentation complémentaire, schémas, exemples ou modèles.
scripts/	No	Scripts Python qui peuvent être exécutés uniquement lorsqu'ils sont explicitement déclarés comme points d'entrée.
assets/	No	Ressources statiques utilisées par la brique.

Ecriture de SKILL.md

Chaque compétence doit inclure la matière première YAML en haut de SKILL.md, suivie des instructions de démarque.

Exemple de base

---
name: sql-helper
description: Helps the agent write safe SQL queries using project schemas.
license: internal
compatibility: "agent-platform"
metadata:
  owner: data-platform
  domain: analytics
allowed-tools: "analyzeQuery inspectSchema"
---

# SQL Helper

Use this skill when the user asks for SQL generation, query review, or schema-aware analysis.

Before writing SQL:
1. Inspect the relevant schema files in `references/`.
2. Prefer explicit column names.
3. Avoid destructive statements unless the user explicitly asks for them and the environment allows them.

Tableau 22-3 Champs de matière première pris en charge

Champ	Obligatoire	Description
name	Oui	Nom de compétence unique utilisé par le catalogue et les outils.
description	Oui	Brève description utilisée pour le repérage et le routage.
licence	No	Licence ou stratégie d'utilisation de la brique.
Compatibilité	No	Note de compatibilité pour les exécutions ou les plates-formes prises en charge.
métadonnées	No	Correspondance de métadonnées de chaîne à chaîne.
outils autorisés	No	Liste d'outils séparés par des espaces que cette brique permet.
points d'entrée	No	Liste des points d'entrée exécutables déclarés par la brique.

Ajout de fichiers annexes

Les fichiers de support permettent à une brique de conserver un contenu détaillé en dehors des instructions principales. Cela maintient SKILL.md concentré tout en donnant à l'agent l'accès à un contexte plus riche. Exemple :

skills/
	sql-helper/
		SKILL.md
		references/
			warehouse_schema.md
			query_style_guide.md
			examples.md

L'agent peut inspecter ces fichiers avec :

list_skill_files("sql-helper", "references")
load_skill_file("sql-helper", "references/warehouse_schema.md")

Utilisez des fichiers de support pour des contenus tels que :

• Schémas de base de données
• Exemples d'API
• Modèles d'invite
• Guides de style
• Glossaires de domaine
• Livres de jeux pas à pas
• Cas de test ou exemples

Création d'une compétence exécutable

Une brique peut éventuellement exposer un comportement exécutable réutilisable via run_skill_entrypoint. Elle est destinée aux opérations contrôlées telles que les calculs, les transformations, la validation ou l'extraction de données structurées.

Les compétences exécutables doivent répondre à deux exigences :

1. La brique doit inclure run_skill_entrypoint dans les outils autorisés.
2. Le script doit être explicitement déclaré dans la section des points d'entrée de SKILL.md.

Exemple de compétence exécutable

skills/
	statistics-helper/
		SKILL.md
		scripts/
			summarize_numbers.py

SKILL.md

---
name: statistics-helper
description: Computes basic summary statistics for numeric data.
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: summarize_numbers
    script: scripts/summarize_numbers.py
    func: run
    description: Returns count, min, max, mean, and median for a list of numbers.
---

# Statistics Helper

Use this skill when the user asks for basic descriptive statistics.
scripts/summarize_numbers.py:
from statistics import mean, median

def run(*, values: list[float]) -> dict:
    if not values:
        raise ValueError("values must not be empty")

    return {
        "count": len(values),
        "min": min(values),
        "max": max(values),
        "mean": mean(values),
        "median": median(values),
    }
Example invocation:
run_skill_entrypoint(
  name="statistics-helper",
  entrypoint="summarize_numbers",
  args_json="{\"values\": [10, 20, 30, 40]}",
  timeout_seconds=10
)
The runner returns structured output that includes exit_code, stdout, stderr, and a best-effort parsed result when the script prints or returns JSON.

Règles pour les points d'entrée exécutables

Les points d'entrée exécutables sont intentionnellement contraints. La plate-forme exécute uniquement les fichiers Python suivants :

• Situé sous le répertoire/scripts de la brique
• Déclaré dans la matière première des points d'entrée de la compétence
• Autorisé par le paramètre allowed-tools de la brique

La plate-forme ne fournit pas d'exécution de script arbitraire à usage général. Les scripts qui ne sont pas déclarés dans SKILL.md ne peuvent pas être exécutés.

Le programme d'exécution de script utilise un délai d'expiration, une valeur par défaut de 10 secondes, exécute Python avec un comportement en mode isolé et applique des restrictions de chemin. Toutefois, l'exécution basée sur un sous-processus n'est pas un modèle d'environnement restreint complet du système d'exploitation. Pour une utilisation en production, une isolation plus élevée, telle que des conteneurs, des systèmes de fichiers restreints ou des contrôles réseau, doit être envisagée.

Autorisations d'outil avec allowed-tools

allowed-tools sert de point de contrôle d'accès de niveau brique. Pour une brique de type documentation uniquement, vous pouvez autoriser uniquement les outils de lecture de fichiers :

allowed-tools: "load_skill_file list_skill_files"

Pour une brique qui peut exécuter des scripts déclarés, incluez run_skill_entrypoint :

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint" 

N'ajoutez pas run_skill_entrypoint sauf si la brique a réellement besoin d'un comportement exécutable.

Comment laisser vos agents découvrir et utiliser les compétences

Pour compléter l'agent par des briques, vous devez instancier un catalogue de briques, un middleware de briques et convertir les briques en outils à l'aide des objets suivants de la bibliothèque aidpUtils :

Outil	Description
discover_skill_catalog	Déterminer les emplacements de recherche de compétences par défaut (projet + utilisateur) Créer un catalogue de compétences à partir des répertoires repérés
SkillMiddleware	Ajoutez la synthèse des compétences et les règles de routage disponibles à l'invite du système. Fournissez des aides d'usine pour la construction de middleware orientés espace de travail.
make_skill_tools	Cette méthode renvoie les outils de repérage de briques : activate_skill, list_skill_files, load_skill_file et run_skill_entrypoint. Ces outils peuvent être utilisés par l'agent pour activer et exécuter différentes briques.

Voici un exemple de ce que votre fichier d'entrée pourrait inclure :

from aidputils.agents.skills.discovery import discover_skill_catalog
from aidputils.agents.skills.middleware import SkillMiddleware
from aidputils.agents.skills.tools.factories import make_skill_tools
...
class SchoolGradeAgentWithEmbededSkills:
	...
	def init(self) -> None: 
		...
		self.catalog = discover_skill_catalog(skill_folder_whitelist=None)
		self.skill_middleware = SkillMiddleware(self.catalog)
		self.tools = make_skill_tools(self.catalog)

Vous pouvez déboguer votre catalogue de briques en ajoutant cette instruction de journaliseur à votre code. Toutes les aptitudes repérées dans le catalogue de briques seront ainsi imprimées :

for info in self.catalog.list():
	logger.info("skill_id=%s name=%s desc=%s root=%s skill_file=%s", info.skill_id, info.name, info.description, info.root_dir, info.skill_file)

Priorité des compétences

La plate-forme peut charger des compétences à partir de plusieurs emplacements, tels que des annuaires de niveau projet et utilisateur. Le catalogue regroupe ces emplacements en une seule liste de briques avec une clé de nom.

Lorsque plusieurs magasins contiennent une brique portant le même nom, la priorité détermine laquelle est utilisée. Les magasins ultérieurs remplacent les précédents, ce qui permet à une application hôte de contrôler si les compétences de niveau utilisateur, de niveau projet ou de niveau espace de travail sont prioritaires.

Meilleures pratiques en matière de création de compétences

Garder SKILL.md concentré

Utilisez SKILL.md pour les instructions de base dont l'agent a besoin immédiatement après l'activation. Placez les schémas longs, les exemples et le matériel de référence dans les références/.

Ecrire des descriptions claires

Le champ de description est utilisé pour le repérage. Rendez-la suffisamment spécifique pour que l'agent sache quand activer la brique.

Bon:

description: Helps generate BigQuery SQL using the finance warehouse schema.

Moins utile :

description: Helps with data.

Utiliser des noms de point d'entrée explicites

Les noms des points d'entrée doivent décrire clairement l'opération :

entrypoints: 
   - name: validate_query 
   - name: summarize_numbers 
   - name: transform_csv

Évitez les noms vagues tels que :

entrypoints: 
   - name: run 
   - name: do_it 

Renvoyer les résultats structurés

Les scripts exécutables doivent renvoyer des résultats sérialisables au format JSON chaque fois que cela est possible. La sortie est ainsi plus facile à inspecter et à utiliser pour l'agent.

Eviter les exécutions inutiles

Préférez les instructions et les fichiers de référence lorsque cela est possible. Utilisez des points d'entrée exécutables uniquement pour les opérations qui nécessitent réellement du code.

Ajouter une nouvelle compétence

Vous pouvez ajouter de nouvelles briques d'agent en créant un dossier dans le répertoire des briques et en ajoutant les fichiers et dossiers nécessaires.

1. Créez un dossier sous le répertoire des briques : .agents/skills/<skill-name>/.
2. Ajoutez un fichier SKILL.md avec le frontmatter requis.

   ---
   name: <skill-name>
   description: <what this skill helps the agent do>
   ---
   

3. Ecrivez les instructions de brique dans Markdown sous le tapis avant.
4. Ajoutez des fichiers annexes facultatifs sous :

   references/
   assets/
   scripts/
   

5. Si la brique est exécutable, ajoutez run_skill_entrypoint à allowed-tools, déclarez entrypoints dans SKILL.md et placez l'implémentation Python sous scripts/.

Ajouter une nouvelle capacité exécutable à une brique existante

Vous pouvez ajouter une nouvelle opération exécutable à une brique existante pour étendre les capacités de SKILL.md.

1. 1. Ajoutez un fichier Python dans le répertoire scripts/ de la brique.

   .agents/skills/<skill-name>/scripts/my_operation.py 

2. 2. Implémentez une fonction run(...).

   def run(*, input_text: str) -> dict:
       return {
           "length": len(input_text),
           "uppercase": input_text.upper(),
       }
   

3. 3. Ajoutez un point d'entrée correspondant à SKILL.md.

   allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
   entrypoints:
     - name: my_operation
       script: scripts/my_operation.py
       func: run
       description: Processes input text and returns structured output.
   

4. 4. Testez le point d'entrée avec un objet JSON en tant qu'arguments.

   {
     "input_text": "hello"
   }
   

Dépannage des aptitudes des agents

Si vous rencontrez des problèmes avec l'implémentation des briques d'agent, consultez cette liste pour obtenir de l'aide sur la résolution de votre problème.

L'agent ne voit pas ma brique

Vérifiez que :

• Le dossier de compétences se trouve sous un répertoire de compétences configuré.
• Le dossier contient SKILL.md.
• SKILL.md a une matière première YAML valide.
• Le frontmatter inclut à la fois le nom et la description.

L'agent active la mauvaise brique

Recherchez les noms de brique en double dans les répertoires de brique. Si deux briques portent le même nom, la priorité du catalogue détermine celle qui est utilisée.

Impossible de charger un fichier de support

Vérifiez que :

• Le fichier se trouve dans le dossier de brique.
• Le chemin n'inclut pas les parcours tels que ../.
• Le fichier n'est pas masqué.
• Le fichier n'est pas exclu, par exemple __pycache__ ou .pyc.

Un point d'entrée ne s'exécutera pas

Vérifiez que :

• run_skill_entrypoint est inclus dans les outils autorisés.
• Le point d'entrée est déclaré dans SKILL.md.
• Le chemin du script se trouve sous scripts/.
• Le script est un fichier .py.
• Le nom de la fonction dans func existe dans le script.
• Les arguments sont un objet JSON valide.

Un point d'entrée expire

Augmentez timeout_seconds uniquement si l'opération devrait prendre plus de temps. Pour les opérations à longue durée d'exécution ou gourmandes en ressources, envisagez de déplacer l'opération vers un service dédié ou un environnement d'exécution plus isolé.

Exemple : Compléter la compétence de l'agent

Cet exemple montre à quoi ressemblerait une brique d'agent complète après l'implémentation.

Structure de dossier

skills/
	customer-support-reply/
		SKILL.md
		references/
			tone_guide.md
			refund_policy.md
			escalation_rules.md

SKILL.md

---
name: customer-support-reply
description: Helps draft customer support replies using the company tone guide and policy references.
allowed-tools: "load_skill_file list_skill_files"
metadata:
  owner: support-operations
  domain: customer-support
---

# Customer Support Reply

Use this skill when the user asks for help drafting, reviewing, or improving a customer support response.

Workflow:

1. Identify the customer’s issue.
2. Load the relevant policy file from `references/` if needed.
3. Draft a clear, empathetic response.
4. Avoid making commitments that are not supported by policy.
5. Recommend escalation when the request matches the escalation rules.
This skill does not run code. It gives the agent structured instructions and optional policy files that can be loaded only when relevant.

Test d'agent

Vous pouvez tester vos agents pour prévisualiser et déboguer leur sortie. Vous pouvez également créer et gérer des sessions de test pour explorer différents scénarios de test pour vos agents.

La première étape pour tester un agent consiste à l'attacher à un calcul d'IA. L'action d'attachement d'un agent transmet une copie de votre agent à un calcul d'IA. Tant que votre agent est attaché à un calcul d'IA, toutes les modifications que vous avez apportées à votre agent sont propagées au calcul attaché chaque fois que vous cliquez sur le bouton Tester.

Une fois que vous avez cliqué sur le bouton Test, vous êtes redirigé vers le playground de test.

Le terrain de jeu de test comporte les composants suivants :

• Une fenêtre de discussion dans laquelle vous pouvez lancer une session et commencer à discuter avec l'agent, ou reprendre une session existante
• Représentation graphique de l'agent
• Panneau présentant une arborescence de traces et d'étendues générées pendant la session
• Panneau de l'explorateur de traces et d'étendues qui affiche les attributs de traces et d'étendues, entrée/sortie. L'onglet Détails inclut les ID, l'heure de début et de fin, l'heure d'exécution, tandis que les onglets Evénements mettent en évidence les erreurs au cours de l'exécution.

Le Playground vous permet d'interagir et de tester chaque agent indépendamment si vous le souhaitez. Par défaut, l'agent superviseur est sélectionné, mais vous pouvez choisir de discuter avec chaque agent exécuteur et de le tester indépendamment. Vous pouvez ainsi simuler le comportement d'un agent superviseur émettant des demandes aux agents exécutifs. Pour ce faire, sélectionnez l'agent à tester dans le menu déroulant de la fenêtre de discussion.

Les traces et les étendues sont affichées dans le panneau central dès que vous créez votre premier message. Chaque tâche correspond à un message utilisateur différent. Vous pouvez cliquer sur le curseur de gauche pour développer la trace et inspecter les étendues.

Tester les agents dans le terrain de jeu

Vous pouvez tester le générateur visuel et les agents basés sur LangGraph à partir du terrain de jeu Test pour valider et déboguer vos agents.

Vous devez avoir un calcul d'IA attaché à votre agent pour effectuer le test. Vous pouvez ajouter un nouveau cluster de calcul d'IA en suivant Création d'un cluster d'IA pour un agent ou en attachant un cluster de calcul d'IA existant en suivant Attachement d'un cluster d'IA existant à un agent.

1. Accédez à votre agent dans votre espace de travail. Cliquez sur le nom d'agent.
2. En haut du canevas, cliquez sur Plan d'accès. La transmission de l'agent vers le calcul associé peut prendre plusieurs secondes.
   
   

   

   
   

Votre agent est affiché dans le terrain de test.

Créer une session de test d'agent

Vous pouvez créer une session de test pour lancer une nouvelle conversation avec votre agent.

Toutes les sessions créées dans la cible de terrain de test sur laquelle l'agent est hébergé sur le calcul associé. Une fois qu'une session est créée, elle peut être reprise ultérieurement.

1. Accédez à votre agent dans votre espace de travail. Cliquez sur le nom d'agent.
2. En haut du canevas, cliquez sur Playground.
3. Dans le sélecteur de session, cliquez sur Créer une session.
   
   

   

   
   
4. Démarrez une boîte de dialogue avec votre agent en saisissant une requête dans la zone de discussion.
   
   

   

   
   

Reprendre une session de test d'agent

Vous pouvez reprendre les sessions de test d'agent que vous avez précédemment créées.

Remarques :

Vous ne pouvez reprendre que les sessions que vous avez créées.

1. Accédez à votre agent dans votre espace de travail. Cliquez sur le nom d'agent.
2. En haut du canevas, cliquez sur Playground.
3. Dans la liste déroulante Session, sélectionnez une session précédente.
   
   

   

   
   
4. Reprenez la boîte de dialogue avec votre agent en saisissant une requête dans la zone de discussion.

Supprimer une session de test d'agent

Vous pouvez supprimer les sessions de test pour les agents hébergés sur le calcul AI attaché et les sessions qui ont été créées sur un agent déployé.

1. Accédez à votre agent dans votre espace de travail.
2. Cliquez sur l'onglet Sessions.
   
   

   

   
   
3. En regard de la session à supprimer, cliquez sur Actions, puis sur Supprimer.
   
   

   

   
   
4. Cliquez sur Supprimer.

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 s'adapter à vos cas d'utilisation.

Les agents prennent en charge les configurations composées d'un seul agent pouvant interagir avec un ou plusieurs outils. Oracle AI Data Platform Workbench 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 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 de flux d'agent via le code LangGraph

Vous ajoutez des outils RAG, SQL et Prompt à 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)

Les paramètres reflètent l'expérience de flux visuel des outils. Pour chaque outil, vous devez fournir :

• 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 ou RAGTool.
• 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.

L'onglet Paramètres de l'outil de code personnalisé comprend les sections suivantes :

• 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 response

Fichier_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.

Voici un exemple de modèle vide d'un élément 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 dans requirements.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 pas package_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 dans requirements.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.

1. Accédez à votre agent.
2. Dans les modèles d'outil, glissez-déplacez un outil personnalisé vers votre canevas.
3. 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é.
   
   

   

   
   
4. Consultez la liste des outils repérés dans la section Outils de l'onglet Package. Chaque classe d'outil figurant dans tool_implementation.py est répertoriée avec son nom, sa description et sa version.
   
   

   

   
   
5. Sélectionnez les outils à activer. Les outils désactivés ne sont pas exposés à l'agent.
6. 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={} 
)

Où :

• <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_AUTH ou BEARER_TOKEN. Dans le cas de BEARER_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.

Si vous ne voyez pas l'outil de serveur MCP personnalisé disponible, vous devrez peut-être redémarrer votre calcul AI existant ou en créer un nouveau.

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.

1. Accédez à votre agent.
2. Dans l'onglet Flux, sous Modèles d'outil, cliquez sur le serveur MCP personnalisé et faites-le glisser vers le canevas.
3. Indiquez l'URL du serveur pour votre serveur MCP.
4. 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.
5. Facultatif : indiquez une description pour le serveur MCP. Le champ de description n'est pas fourni à l'agent.
6. 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.
7. 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.

Lors de la rédaction de la description, vous devez vous concentrer sur :

• • 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}}.

Par exemple, l'URL suivante combine une variable de session pour la région avec un paramètre d'exécution pour le nom du bucket :

https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/o

Lorsque 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.

Trois stratégies d'optimisation sont prises en charge :

• 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 demande HTTP à un flux d'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.

1. Accédez à votre agent.
2. Dans les modèles d'outil, glissez-déplacez un outil de demande HTTP vers votre canevas.
   
   

   

   
   
3. Dans l'onglet Paramètres, indiquez la méthode HTTP. Les méthodes de travail prises en charge sont GET, POST, PUT, PATCH et DELETE.
4. Dans URL, indiquez l'URL complète de l'adresse cible. Vous pouvez utiliser des références de variable de session {{sessionVariables.variable_name}} et des références de paramètre d'exécution {{variable}}. Par exemple : https://api.example.com/users/{{user_id}}/orders.
5. Pour Délai d'expiration, indiquez la durée maximale pendant laquelle l'outil attend une réponse d'une adresse distante en secondes. La valeur maximale du délai d'expiration est 300. Si aucune valeur n'est fournie, la valeur par défaut est de 30 secondes.
6. Dans le menu déroulant Authentification, sélectionnez le type d'authentification approprié.
7. Fournissez les en-têtes de votre demande HTTP. Cliquez sur Ajouter un nouvel pour ajouter des en-têtes supplémentaires.
   
   

   

   
   
8. Indiquez les paramètres de requête pour votre demande HTTP. Cliquez sur Ajouter un nouveau pour ajouter des paramètres supplémentaires.
   
   

   

   
   
9. 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

En principe, les instructions écrites dans un outil d'invite peuvent être directement incluses dans les instructions de l'agent ou fournies directement par l'utilisateur final dans un message utilisateur. Cependant, il y a des situations où l'outil rapide est une meilleure approche :

• 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.

Pour cet exemple, vous devez configurer les paramètres suivants pour l'outil d'invite :

• 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 22-4 Propriétés de configuration de l'outil d'invite

Propriété	Type	Description
llm	objet	Détails et paramètres de connexion LLM
ID_modèle	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.

1. Accédez à votre agent.
2. Dans les modèles d'outil, glissez-déplacez un outil d'invite vers votre canevas.
3. 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.
4. 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.
5. Cliquez sur Appliquer .
6. 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.
7. Cliquez sur Appliquer.
8. 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.
    
    
    
    

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 22-5 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.

1. Accédez à votre agent.
2. A partir des modèles d'outil, faites glisser un outil RAG vers votre canevas.
3. 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.
4. Cliquez sur Appliquer .
5. 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.
6. Cliquez sur Appliquer.
7. 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 de flux d'agents 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.

Par exemple, la requête statique suivante renvoie un ensemble de résultats fixe :

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = 2025 
ORDER BY customer_name 

Le remplacement du littéral par un espace réservé {{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.

Les espaces réservés peuvent apparaître n'importe où dans la requête, y compris dans les fonctions internes. La requête SQL Spark suivante correspond à une valeur de gravité sans distinction majuscules/minuscules :

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 :

Les nom d'espace réservé distinguent 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

Vous pouvez modifier la configuration de l'outil SQL directement en tant que JSON à l'aide de la bascule de vue de code. Ceci est utile pour copier un outil entre les flux ou effectuer des modifications en masse.

{ 
  "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 22-6 Propriétés de configuration de SQL Tool

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 le flux d'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	Placer le nombre de lignes au maximum	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 :

SQL de plate-forme de données Oracle AI

• Grammaire SQL
  • Grammaire SQL du catalogue
  • Grammaire SQL du schéma
  • Grammaire SQL de volume
  • Grammaire SQL de table
  • Requêtes LMD

Spark SQL et Delta Lake (catalogue standard)

Les tables de catalogue standard sont des tables Delta Lake. Le catalogue standard exécute actuellement Spark 3.5 avec Delta Lake 3.2.0.

• 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.

1. Accédez à votre agent.
2. Dans les modèles d'outil, glissez-déplacez un outil SQL vers votre canevas.
3. Cliquez sur la poignée de connecteur de votre agent et faites-la glisser pour vous connecter au noeud d'outil.
   
   

   

   
   
4. Cliquez deux fois sur le noeud SQL pour ouvrir le panneau de configuration.
5. Indiquez un nom et une description pour votre outil. La description est fournie à l'agent et l'aide à décider quand appeler l'outil.
6. 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.
   
   

   

   
   
7. 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é.

   
   

   

   
   
8. 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.
   
   

   

   
   
9. 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.
   
   

   

   
   
10. Sélectionnez Nombre maximal de lignes à renvoyer pour limiter le nombre de lignes renvoyées par les résultats de la requête.

    Remarques :

    Si votre requête peut renvoyer plus de lignes que cette limite, envisagez d'ajouter des paramètres de recherche tels que {{customer_name}} ou {{region}} afin que l'agent puisse trouver des données plus spécifiques.
11. 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.
    
    

    

    
    
12. 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.

Mémoire d'agent

La mémoire de l'agent est la partie d'un système d'agent AI qui permet à l'agent de conserver et de réutiliser les informations sur les virages, les tâches ou les sessions.

Contrairement à la fenêtre de contexte du modèle, qui est temporaire et limitée à l'invite actuelle, la mémoire peut persister des faits, des préférences, des décisions antérieures, des sorties d'outil, des plans intermédiaires ou des observations sur l'environnement.

Mémoire d'agent dans la plate-forme de données AI

AI Data Platform fournit une mémoire à court terme qui est limitée à la durée d'une session. Vous pouvez configurer ce qui peut être conservé en mémoire dans l'onglet Mémoire de votre agent.

Configuration de mémoire à agent unique

La configuration de la mémoire d'un système à agent unique se trouve dans l'onglet Mémoire du noeud d'agent.

Configuration de la mémoire	Description
Activer la mémoire de l'agent	Ce paramètre active la mémoire de l'agent. Lorsqu'il est désactivé, l'agent est essentiellement un système sans état. Chaque tour est traité indépendamment, et aucune question de suivi ne peut être posée. Nous vous recommandons d'activer la mémoire.
Limiter l'historique des conversations	Lorsque cette sélection est désactivée, les tours précédents remplissent la mémoire jusqu'à ce que le modèle soit à court de contexte et qu'une erreur soit renvoyée. Si des sessions courtes sont attendues, il est acceptable de désactiver ce paramètre. Cependant, pour la plupart des cas d'utilisation, nous vous recommandons de limiter l'historique des conversations.
Configuration de la troncature	Si vous choisissez de limiter l'historique des conversations, vous pouvez décider de tronquer l'historique en procédant comme suit : Conserver uniquement les N derniers messages (utilisateur + agent) Définir un budget global pour les jetons (premier entré, premier sorti) Ou les deux, selon la première occurrence, déclenche la troncation de la mémoire de l'agent
Limites maximales de messages	Si vous choisissez de conserver les N derniers messages, vous pouvez définir la valeur N.
Budget du jeton	Vous pouvez également définir un budget global de jetons. Les premiers jetons sont éliminés pour conserver les plus récents en mémoire.

Configuration de la mémoire système multi-agent (modèle de superviseur)

La mémoire d'un système multi-agent est configurée dans l'onglet Mémoire de l'agent superviseur.

La mémoire d'un système multi-agent est appliquée et ne peut pas être désactivée. Les options de troncation de mémoire affichées dans le noeud de l'agent superviseur sont appliquées uniquement à la mémoire de l'agent superviseur. Chaque stratégie de troncation de mémoire d'agent d'exécuteur peut être configurée dans l'onglet Mémoire du noeud d'exécuteur en fonction de la stratégie d'isolement d'état sélectionnée pour l'ensemble du système.

La configuration de la mémoire système multi-agent vous permet également de sélectionner la stratégie de partage de mémoire des agents exécutifs. Trois options sont possibles : Sans conservation de statut, Privé et Partagé. La stratégie est appliquée à tous les agents exécutifs.

Isolation d'état pour les agents exécutifs	Description
Sans conservation de statut	Chaque agent exécuteur ne voit que la tâche affectée par le superviseur. Aucun historique n'est reporté entre les appels. Aucune demande de suivi ne peut être adressée à l'agent superviseur par l'agent exécuteur. Si l'option sans conservation de statut est sélectionnée, la mémoire de chaque agent exécuteur est désactivée.
Privé	Chaque agent exécuteur ne voit que ses propres interactions passées. Il ne peut pas voir d'autres agents exécutifs ni la conversation utilisateur d'origine avec l'agent superviseur.
Partagé	Les agents exécutifs peuvent consulter l'historique complet des conversations entre les agents et l'utilisateur. Tous les agents travaillent à partir d'un contexte partagé. Si elle est sélectionnée, vous pouvez configurer la stratégie de troncation de mémoire séparément pour chaque agent exécuteur dans l'onglet Mémoire de chaque noeud d'agent.

Variables de session

Vous pouvez utiliser des variables de session personnalisées définies par l'agent pour fournir des points de données contextuelles supplémentaires à vos agents au cours d'une session utilisateur.

Définition des variables de session

Les variables de session personnalisées définies par l'agent fournissent des points de données contextuels supplémentaires à l'agent au cours d'une session utilisateur. Les variables peuvent être utilisées à diverses fins, notamment en définissant des valeurs de paramètres dans les outils, en donnant des instructions générales à un agent et en fournissant des informations contextuelles sur l'appelant et/ou l'application dans laquelle l'agent est intégré.

Voici un scénario simplifié dans lequel nous créons un agent de support client. L'agent de support client est intégré à un site Web de vente au détail. Lorsqu'un utilisateur se connecte au site Web de vente au détail, les informations sur cet utilisateur sont capturées par l'application client (ID utilisateur, nom d'utilisateur, emplacement géographique, appareil utilisé, ID panier, etc.) et ces informations peuvent être utilisées par l'agent de support en aval. Examinons un exemple de la façon dont ces paramètres de session peuvent être utilisés dans le champ des instructions d'agent dans AIDP :

You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.  
A few guidelines before your start:  
    You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}?  

Trois variables de session sont utilisées dans l'exemple ci-dessus :

• userName
• Salutation préférée
• currentUserGeo

L'agent n'a aucune connaissance préalable de l'utilisateur interagissant avec le site Web de vente au détail, ne sait pas quel est l'emplacement de l'utilisateur ou n'a aucun contexte sur ce qui se trouve dans le panier de l'utilisateur. En principe, l'application client peut connaître l'ensemble ou un sous-ensemble de ces valeurs et transmettre ces valeurs dans une demande à l'agent. Voici un exemple de ce à quoi pourrait ressembler une demande adressée à l'agent, y compris les paramètres de session.

Remarques :

Cet exemple illustre à quoi pourrait ressembler cette demande. Il n'est pas représentatif d'une décision d'implémentation.

"input": [  
{ "role": "user", 
         "content": [  
{ "type": "input_text”,  
	  "text": "What material is the belt Mr Outcast made of?", 
	  “variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]  
} 
  ]  
} 
] 

L'agent répondrait : "Bonjour M. Paul, quel temps fait-il aujourd'hui à Cancun, Mx ?"

Une autre utilisation de ces paramètres de session consiste à définir des valeurs de paramètre dans les outils. Par exemple, une interrogation SQL peut extraire le contenu d'un panier à l'aide du paramètre de session {{sessionParam.CartID}}} :

Select productID, productName, productDescription, 
productPrice from cartTable where cartID == 
{{sessionVariable.cartID}}  

Les variables de session sont définies par le développeur d'agent lorsqu'il crée ses agents et les valeurs de ces attributs sont définies par l'application client lors de la création ou de la reprise d'une session.

Vous pouvez configurer les paramètres suivants lors de la création d'une variable de session :

Paramétrage	Description
Variable requise	Activez cette option pour rendre cette variable de session obligatoire pour chaque appel d'appel de l'agent. La désactivation rend la variable de session facultative pour chaque appel d'appel.
Variable de journal	Activer pour capturer la valeur de la variable de session dans les journaux et les traces. La désactivation empêche la variable d'apparaître dans les journaux. Nous vous recommandons de désactiver ce paramètre pour les variables avec des données sensibles.
Nom	Nom de la variable de session. Utilisez un nom descriptif pour faciliter la détermination de l'objectif de la variable pour vous et les autres utilisateurs.
Valeur par défaut	Si elle est définie, la valeur par défaut est affectée à la variable de session si aucune autre valeur n'est définie dans l'appel d'appel. Si aucune valeur n'est indiquée, une valeur doit être affectée dans le cadre de l'appel d'appel.
Description	Description de la variable de session. Fournissez une description utile pour que vous et d'autres utilisateurs puissiez comprendre la fonction de la variable de session.

Exemple : utilisation de variables de session dans la configuration des outils

Vous pouvez utiliser une variable de session dans une configuration d'outil SQL dans le cadre de la requête SQL elle-même.

Dans cet exemple, la variable de session geo est utilisée pour filtrer le résultat de la requête SQL :

Vous pouvez utiliser des variables de session et des paramètres d'outil dans la même requête. Dans l'exemple ci-dessous, le paramètre titleID est défini par l'agent tandis que la variable de session geo est fournie par l'application appelante.

Variables de session générées par le système

Les variables de session sont générées automatiquement lorsqu'un serveur MCP distant est connecté à un agent et que le serveur MCP nécessite une authentification, comme un jeton de support.

La variable de session contient la valeur du jeton porteur. Le nom de cette variable de session générée par le système ne peut pas être modifié et est une variable obligatoire. La variable système est supprimée lorsque le noeud MCP est supprimé du canevas.

Dans Playground, vous indiquez une valeur pour la variable de session générée par le système. Dans ce cas, vous devez fournir un jeton porteur pour utiliser le serveur MCP. Vous pouvez sélectionner le même jeton (ou un autre) que celui que vous avez utilisé lors de la configuration du noeud MCP.

Il en va de même si vous déployez l'agent. Vous devrez fournir un jeton d'autorisation. Pour plus d'informations, reportez-vous à Affectation de valeurs aux variables de session à partir de la zone de lecture.

Exemple : affectation de valeurs à des variables de session lors de l'appel d'une adresse déployée

Dans cet exemple, vous disposez de deux variables de session : userLocation et UserName, l'application client transmet les valeurs de variable de session via le champ metadata de body. Nous allons montrer comment affecter des valeurs via Python et via l'interface de ligne de commande OCI.

Si vous utilisez la bibliothèque de demandes Python, la charge utile est la suivante :

body = { 

            "isStreamEnabled" : False, 

            "trace" : False, 
            "input" :[{ 
                "role":"User", 
                "content":[{ 
                    "type" : "INPUT_TEXT", 
                    "text" : “Hello how can you help me?”                  
                }] 
            }], 

            "metadata": { 
            "sessionvariables.userLocation": "Canada",  
            "sessionvariables.UserName": "George" 
        } 
        } 

response = requests.post( 
url = <insert-chat-url>,  
params = None,  
auth = <insert-oci-signer>, 
json = body, 
headers={“x-session-id": <insert-a-session-key>,} 
)  

Sinon, si vous utilisez l'interface de ligne de commande OCI, la charge utile est la suivante :

oci raw-request \ 
  --http-method POST \ 
  --auth security_token \ 
  --request-body '{ 
    "isStreamEnabled": false, 
    "input": [ 
      { 
        "role": "user", 
        "content": [ 
          { 
            "type": "INPUT_TEXT", 
            "text": "Hello how can you help me?" 
          } 
        ] 
      } 
    ], 
    "metadata": { 
      "sessionvariables.userName": "George", 
      "sessionvariables.userLocation": "Canada"}" 
    } 
  }' \ 
  --request-headers '{ 
    "x-session-id": "george-session-may11" 
  }' \ 
  --target-uri "<insert-your-agent-flow-uri>" 

Créer une variable de session dans l'onglet Variables de l'agent

Vous pouvez créer une variable de session et l'ajouter à votre agent à partir de l'onglet Variables.

1. Accédez à l'agent auquel vous voulez ajouter une variable de session.
2. Cliquez sur l'onglet Variables.
   
   

   

   
   
3. Cliquez sur Ajouter une variable de session.
   
   

   

   
   
4. Cochez cette case si la variable de session est obligatoire.
5. Indiquez si la valeur de la variable de session doit être enregistrée dans les journaux et les traces. Laissez ce paramètre désactivé pour les données confidentielles.
6. Fournissez une description et un nom explicites pour la variable de session.
7. Indiquez une valeur par défaut pour la variable de session. La valeur par défaut est affectée à la variable de session si aucune autre valeur n'est affectée dans le cadre de l'appel.
8. Cliquez sur Créer.

Reportez-vous aux variables de session dans les instructions de flux d'agent

Vous pouvez faire référence aux variables de session dans les instructions d'agent et les configurations d'outils, y compris la requête SQL et l'outil d'invite.

1. Accédez au flux de l'agent.
2. Cliquez sur le noeud SQL ou Invite de l'outil Playground.
   
   

   

   
   
3. Dans le champ Requête, commencez à saisir {{sessionvariables.
4. Sélectionnez la variable de session dans la liste des variables de session existantes.

Affichage des agents et des outils à l'aide d'une variable de session

Vous pouvez afficher la liste des agents et des outils à l'aide d'une variable de session spécifique dans l'onglet Variable du flux d'agent.

1. Accédez à un flux d'agent à l'aide de la variable de session pour laquelle vous voulez visualiser les agents et outils associés.
2. Cliquez sur l'onglet Variable.
3. En regard de Utilisé dans : pour votre variable de session, cliquez sur le menu déroulant. La liste des agents et des outils utilisant la variable de session apparaît.

Affecter des valeurs aux variables de session à partir du Playground de test

Vous pouvez affecter des valeurs aux variables de session à tout moment à partir de l'onglet Playground de test.

1. Accédez au flux de l'agent.
2. En haut de la zone de mémoire, cliquez sur Paramètres de session. La liste de toutes les variables de session du flux d'agent apparaît.
   
   

   

   
   
3. Modifiez les variables de session. Après la reprise de la session Playground de test, les valeurs des dernières variables de session affectées sont utilisées.
   
   

   

   
   

Glissières de sécurité

Les garde-corps sont des mécanismes de sécurité pour guider et contrôler le comportement des agents d'IA.

Dans Oracle AI Data Platform Workbench, les garde-corps sont configurés pour empêcher la génération ou la consommation de contenu toxique et malveillant par les flux d'agents. Les garde-corps empêchent également la fuite d'informations personnellement identifiables (PII) par le flux d'agent. Les garde-fous spécifiques disponibles dans AI Data Platform Workbench s'appliquent à la modération de contenu, à l'injection rapide et aux informations d'identification personnelle.

Remarques :

Les garde-corps proposés par Oracle AI Data Platform Workbench ne sont disponibles qu'en anglais.

Les garde-corps proposés dans AI Data Platform Workbench sont implémentés par l'équipe de service OCI Generative AI. Reportez-vous à Guardrails pour OCI Generative AI. En fonction de votre configuration de garde-corps, le service AI Data Platform Workbench appelle l'API Apply Guardrails dans votre location OCI.

Guardrails dans Visual Flow Canvas

Par défaut, aucun garde-corps n'est appliqué à votre système au-delà des contrôles de sécurité natifs du fournisseur de modèle. Pour ajouter des garde-corps, vous devez faire glisser un noeud de garde-corps vers le générateur de flux visuel de l'agent et le connecter à l'agent.

Un noeud de garde-corps peut filtrer le trafic entre un déclencheur de discussion et un noeud d'agent, entre un superviseur et des agents exécutifs, ou entre des noeuds d'agent et d'outil. Pour la plupart des scénarios, nous recommandons un seul noeud de garde-fous entre le déclencheur de discussion et le noeud d'agent. Cela garantit que tous les messages de l'utilisateur entrant et les messages générés par l'agent seront filtrés par les garde-corps.

Le noeud de garde-corps ne peut être inséré qu'entre :

• Un noeud de déclencheur de discussion et un agent (superviseur ou exécuteur)

Quels sont les garde-corps disponibles ?

Le diagramme ci-dessous illustre une interaction simple entre un utilisateur final et un agent. Dans ce scénario, tous les guadrails sont appliqués (modération de contenu – CM, prévention des injections rapides – PI, et détection des PII – PII). PI n'est appliqué qu'à la requête utilisateur.

Après le second message émis par l'utilisateur final, une tentative PI a été détectée et le message utilisateur a été bloqué suite à l'action sélectionnée par le développeur de l'agent sur la détection PI (bloc).

Modération du contenu

La modération de contenu est une implémentation courante des garde-fous dans la plupart des IA génératives. Non coché, les LLM peuvent générer du contenu nuisible, promouvoir du contenu violent, raciste et sexuellement explicite. Il est impératif de donner aux développeurs d'agents une visibilité et un contrôle complets sur la façon dont les interactions des utilisateurs avec les agents sont surveillées et analysées à la recherche de contenu potentiellement dangereux. La modération du contenu empêche le contenu haineux, sexuel, violent, toxique, péjoratif ou fondé sur le harcèlement d'être considéré ou généré par le flux d'agent. Notre modèle de garde-corps classe le contenu selon ces six catégories et signale le contenu qui appartient à l'une de ces catégories.

Vous pouvez choisir d'effectuer une action sur la requête d'entrée utilisateur ou la réponse de modèle :

• Bloquer : vous empêchez l'agent de traiter l'entrée utilisateur et de générer une réponse. Les utilisateurs reçoivent une réponse d'erreur du flux d'agent.
• Informatique : vous autorisez le flux d'agent à traiter l'entrée utilisateur et à générer une réponse. L'agent informe l'utilisateur que l'entrée ou la réponse contenait un contenu répondant aux critères de garde-corps.
• Autoriser : vous autorisez le traitement et/ou la génération de contenu potentiellement dangereux par le flux d'agent.

L'action Bloquer est sélectionnée pour la modération de contenu lorsque vous créez un flux d'agent. Oracle recommande de conserver Bloquer comme sélection de garde-corps pour la modération de contenu.

Injection d'invite

Les garde-fous d'injection rapide pour les agents d'IA sont un mécanisme de protection qui détecte, prévient et atténue les instructions malveillantes ou involontaires intégrées dans les entrées utilisateur. Les attaques par injection d'invite tentent de remplacer ou de modifier les instructions, stratégies ou objectifs d'origine de l'agent en insérant un texte masqué indiquant au modèle d'ignorer les règles précédentes, d'éliminer les secrets ou d'exécuter des actions non autorisées.

Vous pouvez choisir les mêmes actions que pour la modération de contenu : bloquer, informer ou autoriser. Les garde-fous d'injection d'invite s'appliquent uniquement à la requête d'entrée utilisateur.

• Bloquer : vous empêchez l'agent de traiter l'entrée utilisateur. Les utilisateurs reçoivent une réponse d'erreur du flux d'agent.
• Informatique : vous autorisez le flux d'agent à traiter l'entrée utilisateur. L'agent informe l'utilisateur que l'entrée contenait un contenu répondant aux critères de garde-corps.
• Autoriser : vous autorisez le traitement de contenu potentiellement dangereux par le flux d'agent.

L'action Bloquer est sélectionnée lorsque vous créez un flux d'agent. Oracle recommande de conserver Block comme sélection de garde-corps pour l'injection rapide.

Informations d'identification personnelles (PII)

Les garde-corps PII détectent, bloquent ou masquent automatiquement les informations d'identification personnelle des requêtes d'entrée utilisateur ou des réponses des agents. Ce garde-corps empêche l'agent d'exposer les informations sensibles des utilisateurs d'une manière qui viole les réglementations de confidentialité ou les politiques organisationnelles.

Les garde-corps PII prennent en charge quatre types d'entité :

• Courriel
• Numéro de téléphone
• Adresse physique
• Nom du patient

Pour chacune de ces quatre entités, vous choisissez d'appliquer l'une des actions suivantes que votre agent effectue sur la requête utilisateur d'entrée ou la réponse de l'agent :

• Bloquer : vous empêchez l'agent de traiter l'entrée utilisateur et de générer une réponse. Les utilisateurs reçoivent une réponse d'erreur du flux d'agent.
• Informatique : vous autorisez le flux d'agent à traiter l'entrée utilisateur et à générer une réponse. L'agent informe l'utilisateur que l'entrée ou la réponse contenait des informations d'identification personnelle.
• Masque : vous autorisez le flux d'agent à traiter l'entrée et à générer une réponse masquée. Toutes les informations d'identification personnelle utilisées sont occultées pour éviter toute exposition.
• Autoriser : vous autorisez le traitement et/ou la génération de données d'identification personnelle par le flux d'agent.

Dans un nouveau flux d'agent, les informations d'identification personnelle sont autorisées à la fois en entrée utilisateur et en réponse par défaut. Oracle vous recommande de sélectionner soigneusement la garde-corps pour les informations d'identification personnelle en fonction de vos besoins en matière de sécurité.

Activer des garde-corps spécifiques dans un noeud

Vous pouvez choisir les garde-corps à activer et la façon dont chacun est configuré lors de l'ajout d'un noeud de garde-corps à votre canevas visuel.

1. Accédez au flux d'agent dans votre espace de travail.
2. Faites glisser un noeud Guardrails de votre palette vers votre canevas.
3. Fournissez une description et un nom explicites pour le noeud.
   
   

   

   
   
4. Activez une glissière de sécurité pour l'activer et commencez à la configurer. Le fait d'appuyer à nouveau sur la bascule désactive la garde-corps et ses configurations.
   
   

   

   
   
5. Sélectionnez la configuration de garde-corps nécessaire pour chaque catégorie.
   
   

   

   
   

Création d'un cluster AI pour un agent

Vous pouvez créer un cluster AI directement à partir de l'interface d'agent et l'attacher immédiatement.

Pour plus d'informations, reportez-vous à Calcul AI.

1. Sur la page d'accueil, accédez à votre agent.
2. Cliquez sur Compute, puis sur Créer un calcul d'IA.
3. Fournissez un nom et une description pour votre cluster de calcul AI.
4. Sélectionnez le nombre d'OCPU et la taille de mémoire pour votre cluster de calcul AI.
5. Cliquez sur Créer.

Attachement d'un cluster AI existant à un agent

Vous pouvez attacher un cluster AI que vous avez précédemment créé à un agent sur lequel vous disposez au moins des droits d'accès USE.

1. Sur la page d'accueil, accédez à votre agent.
2. Cliquez sur Compute, puis sur Attacher à AI Compute.
3. Cliquez sur le cluster à utiliser dans la liste.
   L'agent affiche AIcompute : (ClusterName) en cours d'exécution lorsqu'il a été attaché. Cette opération peut prendre plusieurs minutes.

Détachement d'un agent d'AI Compute

Vous pouvez détacher un agent d'un calcul d'IA. Le détachement du calcul AI enlève le code d'agent exécuté sur le calcul attaché et empêche les tests.

Remarques :

Le détachement d'un agent du calcul AI ne supprime pas l'agent. Vous pouvez reprendre la création et le test de l'agent en l'attachant au même calcul d'IA ou à un calcul d'IA différent.

1. Sur la page d'accueil, accédez à votre agent.
2. Cliquez sur Compute, puis sur Détacher de AI Compute.
   
   

   

   
   

Déploiement d'agent A2A

Le protocole Agent2Agent (A2A) est une norme ouverte pour la communication entre les agents d'IA indépendants, y compris les agents construits avec différentes structures, hébergés par différents fournisseurs ou exécutés en tant que systèmes distants opaques.

Son but est de donner à ces agents un modèle d'interaction partagé afin qu'ils puissent découvrir les capacités de l'autre, négocier les formats d'entrée/sortie pris en charge, déléguer ou collaborer sur des tâches et échanger des informations en toute sécurité sans exposer la mémoire interne, les outils ou les détails d'implémentation. Pour plus d'informations, reportez-vous à la section Agent2Agent (A2A) Protocol.

A2A est destiné à résoudre l'interopérabilité des agents : au lieu que chaque intégration d'agent soit personnalisée, un client ou un autre agent peut interagir avec n'importe quel agent distant compatible A2A en utilisant un ensemble commun de concepts et d'opérations. La spécification se concentre sur les messages, les tâches, les pièces, les artefacts, les mises à jour en continu et les notifications push. Elle prend en charge les réponses synchrones, le travail asynchrone à longue durée d'exécution, la diffusion en continu et les modèles d'authentification/sécurité de type entreprise.

Dans Oracle AI Data Platform, tous les agents déployés disposent d'un chemin d'appel /A2A qui peut être appelé par les applications client A2A.

Qu'est-ce qu'une carte agent ?

Une carte d'agent est un document de métadonnées JSON publié par un serveur A2A. Dans AIDP, le serveur A2A est le calcul AI qui héberge votre déploiement d'agent.

La carte décrit l'identité de l'agent, l'adresse de service, les protocoles/transports pris en charge, les capacités, les compétences, les modes d'entrée/sortie pris en charge et les exigences d'authentification. Les clients l'utilisent pour déterminer si l'agent convient et comment l'appeler. Une carte d'agent correctement documentée est une exigence du protocole A2A.

Les cartes d'agent dans AI Data Platform Workbench sont à l'état Brouillon, ce qui signifie que l'agent n'a pas été déployé ou Publié, ce qui signifie que la carte a été déployée avec l'agent.

Actions de carte d'agent

Pendant le développement d'un agent, la carte est disponible dans le menu Actions de l'agent.

Deux cartes d'agent sont accessibles :

• Le projet de carte reflète l'état actuel de l'agent en développement.
• La carte publiée correspond à un instantané de la carte prise lors du déploiement de l'agent. La carte publiée reflète l'état de l'agent déployé.

Champs de carte d'agent

AI Data Platform Workbench prend en charge un sous-ensemble des champs de carte d'agent de protocole A2A actuels, disponibles ici : Protocole A2A - Carte d'agent.

Champ	Obligatoire	Description
name	Oui	Nom lisible par l'utilisateur pour l'agent. Exemple : "Agent recette"
description	Oui	Description lisible par l'homme de l'agent, qui aide les utilisateurs et autres agents à comprendre son but. Exemple : "Agent qui aide les utilisateurs avec des recettes et de la cuisine."
Agent Version	Oui	Version de l'agent. Exemple : "1.0.0"
Documentation URL	No	URL fournissant une documentation supplémentaire sur l'agent.
Provider - Organization	No	Fournisseur de services de l'agent.
Provider - URL	No	URL du fournisseur de services.
Capabilities	Oui	Jeu de fonctionnalités A2A pris en charge par l'agent. Seul streaming peut être configuré (Vrai/Faux)
Skills	Oui	Les compétences représentent les capacités d'un agent. Il s'agit en grande partie d'un concept descriptif, mais il représente un ensemble de comportements plus ciblés que l'agent est susceptible de réussir. Les compétences représentent un éventail de compétences d'agent.

Chaque AgentSkill est constitué de plusieurs champs documentant les capacités de l'agent. La définition des compétences de l'agent dans la carte d'agent est l'opération la plus longue et un processus itératif. Les compétences peuvent être modifiées (ainsi que le reste de la carte d'agent) dans la carte d'agent provisoire avant le déploiement.

Remarques :

inputModes, outputModes et securityRequirements sont fournis par AI Data Platform Workbench et ne peuvent pas être modifiés.

Champ	Obligatoire	Description
Skill ID	Oui	Identificateur unique de la brique de l'agent.
Skill Name	Oui	Nom lisible par l'utilisateur pour la brique.
Description	Oui	Description détaillée de la brique.
Tags	Oui	Ensemble de mots-clés décrivant les capacités de la brique.
Examples	No	Exemples d'invites ou de scénarios que cette brique peut gérer.

Chemin A2A de l'adresse de déploiement d'agent

Un chemin /a2a est exposé dans l'URL d'un agent déployé en plus de /chat.

Par exemple, un agent exposera ces chemins aux clients externes :

• https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/chat
• https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a

Les deux chemins (/chat, /a2a) peuvent être utilisés par des clients distincts.

Variables de session dans A2A

Les valeurs des variables de session peuvent être transmises à un agent A2A dans le champ de message metadata. Le fragment de code JSON ci-dessous affiche la charge utile d'un message utilisateur envoyé à l'agent a2a avec trois variables de session : userName, geoLocation et os :

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "contextId": "session_12345",
    "taskId": "task_67890",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "What is the current status of my order?",
        }
      ],
      "metadata": {
        "sessionvariables.userName": "George",
        "sessionvariables.geoLocation": “Dallas, TX”,
        "sessionvariables.os": "mobile_ios"
      }
    }
  },
  "id": "rpc-99821"
}

Exemple : appel d'un agent A2A avec l'interface de ligne de commande OCI (non-streaming)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": "<your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<your-user-principal>"
  }' \
  --target-uri " <your-a2a-agent-endpoint-url>"

Exemple : appel d'un agent A2A avec l'interface de ligne de commande OCI (Streaming)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/stream",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": " <your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<user-principal>"
  }' \
  --target-uri "<your-a2a-agent-endpoint-url>"

Exemple : SDK client A2A

import asyncio
import json
import logging
import typing
from collections.abc import Iterator
import uuid
import httpx
import oci
from a2a.client import A2AClient, ClientFactory
from a2a.types import (
    AgentCard,
    Message,
    Part,
    Role,
    TextPart,
    SendMessageRequest,
    MessageSendParams,
    MessageSendConfiguration,
    Task, SendMessageSuccessResponse, SendStreamingMessageRequest,
)

class OCIAuth(httpx.Auth):
    """httpx auth implementation using OCI signer via requests auth adapter."""

    def __init__(self, signer: oci.signer.AbstractBaseSigner):
        self._requests_auth = _OCIRequestsAuth(signer)

    def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
        req = RequestsRequest(
            method=request.method,
            url=str(request.url),
            headers=dict(request.headers),
            data=request.content,
        )
        prepared: RequestsPreparedRequest = req.prepare()
        prepared = self._requests_auth(prepared)
        request.headers.update(dict(prepared.headers))
        yield request



def getOCIAuth():
    conf = oci.config.from_file(profile_name="DEFAULT")
    token_file = conf['security_token_file']
    token = None
    with open(token_file, 'r') as f:
        token = f.read()
    private_key = oci.signer.load_private_key_from_file(conf['key_file'])
    signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
    auth = OCIAuth(signer=signer)
    return auth


async def _call_agent_with_a2a(agent_url: str, query: str, context_id: str,auth:OCIAuth) -> str:
    """Call an agent using the A2A protocol."""
    try:
        # Initialize OCI signer
        #headers = {"dh-user-principal": "dh-user"}
        headers = {"Accept": "*/*",
                   "dh-user-principal": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

        async with httpx.AsyncClient(timeout=60.0, auth=auth,headers=headers) as hc:
            agent_card = await _get_agent_card(agent_url,auth)
            print(f"Agent card is {agent_card}")

            client =  A2AClient(httpx_client=hc, agent_card=agent_card)
            # Create message
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
                metadata={"sessionvariables.cred.mcp.weatherReportMCP.bearer": "valid-123"}
            )
            request = SendMessageRequest(
                id=str(uuid.uuid4()),  # Add the required id field
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            #json_string = json.dumps(message, indent=4)
            print(f"Send request : {request}")

            response = await client.send_message(request)

            logging.info("Received response from A2A server: %s", response.root.result)
            # Extract response
            result = response.root.result
            # Handle different response types


            if isinstance(result, Task):
                # Task response
                if result.artifacts:
                    # Extract text from artifacts
                    texts = []
                    for artifact in result.artifacts:
                        for part in artifact.parts:
                            if hasattr(part, "root") and hasattr(part.root, "text"):
                                texts.append(part.root.text)
                    return "\n".join(texts) if texts else "Task completed with no text response"
                elif result.status and result.status.message:
                    logging.info(f"Received Task status {result.status.state} from A2A server and status message is {result.status.message}", result.status.message)
                    if  result.status.state== "failed":
                        print("Failure observed in Task invocation")
                        for m_part in result.status.message.parts:
                           print(f"Error message  { m_part.root.text}")

                    return get_message_text(result.status.message)
                else:
                    return f"Task {result.id} status: {result.status.state if result.status else 'unknown'}"

            elif isinstance(result, Message):
                return get_message_text(result)
            else:
                logging.warning(f"Unexpected response type: {type(result)}")
                return "Received response but unable to extract text"
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"


async def _call_agent_with_a2a_with_stream(agent_url: str, query: str, context_id: str, auth: OCIAuth) -> str:
    """Call an agent using the A2A protocol with streaming (SSE) and return the final artifact text."""
    try:
        async with httpx.AsyncClient(timeout=60.0, auth=auth) as hc:
            agent_card = await _get_agent_card(agent_url)
            if not agent_card:
                return "No Agent Card Found"
            print(f"Agent card is {agent_card}")

            client = A2AClient(httpx_client=hc, agent_card=agent_card)
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
            )
            request = SendStreamingMessageRequest(
                id=str(uuid.uuid4()),
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            print("Invoking Remote Agent request (beautified JSON):")
            print(json.dumps(request.model_dump(), indent=2, ensure_ascii=False))
            # Expected event types:
            # - TaskStatusUpdateEvent (working/in-progress)
            # - TaskArtifactUpdateEvent (contains Artifact.parts[].root.text) -> final output
            final_artifact_text_parts: list[str] = []

            async for event in client.send_message_streaming(request):
                # Print each SSE event as-is (SDK object)
                print(f"[A2A stream event] {event}")

                try:
                    result = getattr(event.root, "result", None)
                    if not result:
                        continue

                    # TaskArtifactUpdateEvent and TaskStatusUpdateEvent are SDK types; to avoid tight coupling,
                    # extract by attribute presence.
                    artifact = getattr(result, "artifact", None)
                    if artifact and getattr(artifact, "parts", None):
                        for part in artifact.parts:
                            root = getattr(part, "root", None)
                            txt = getattr(root, "text", None)
                            if txt:
                                final_artifact_text_parts.append(txt)
                except Exception:
                    # Keep streaming even if an event can't be parsed
                    continue

            return "\n".join([t for t in final_artifact_text_parts if t]).strip() or "Stream completed (no artifact text)."
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"

Modifier une carte d'agent provisoire

Vous pouvez modifier la carte d'agent d'un agent qui n'est pas encore déployé.

1. Accédez à votre agent.
2. Cliquez sur Actions, puis sur Visualiser la carte d'agent et Provisionner la carte d'agent.
   
   

   

   
   
3. Cliquez sur Modifier.
   
   

   

   
   
4. Vous pouvez changer de vue en cliquant sur Formulaire ou JSON en haut à droite. La vue JSON est plus complète, mais en lecture seule. Vous pouvez uniquement modifier les champs de la vue Formulaire.
   
   

   

   
   
5. Modifiez les champs selon vos besoins.
6. Cliquez sur Ajouter une brique pour ajouter les briques à exposer aux clients A2A.
   
   

   

   
   
7. Cliquez sur Enregistrer.

Modifier une carte d'agent publiée

Vous pouvez modifier une carte d'agent publiée sans avoir à annuler le déploiement ou à redéployer un agent.

La carte publiée correspond à un instantané de la carte provisoire au moment du déploiement.

Remarques :

Les modifications apportées à une carte publiée sont immédiatement répercutées dans le fichier agent-card.json accessible aux clients A2A.

1. Accédez à votre agent.
2. Cliquez sur Actions, puis sur Visualiser la carte d'agent et sur Carte d'agent publiée.
   
   

   

   
   
3. Vous pouvez changer de vue en cliquant sur Formulaire ou JSON en haut à droite. La vue JSON est plus complète, mais en lecture seule. Vous pouvez uniquement modifier les champs de la vue Formulaire.
4. Cliquez sur Modifier.
   
   

   

   
   
5. Modifiez les champs selon vos besoins.
6. Cliquez sur Ajouter une brique pour ajouter les briques à exposer aux clients A2A.
   
   

   

   
   
7. Cliquez sur Publier les modifications.

Les cartes d'agent publiées ne sont pas accessibles au public. Un utilisateur doit être authentifié et disposer du droit d'accès (READ) pour inspecter le contenu de agent-card.json. D'autres agents peuvent repérer les fonctionnalités et les métadonnées de vos agents via une demande HTTP GET sur le chemin standard :

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a/agent-card.json

Déploiement de l'agent

Le déploiement d'un agent transforme l'agent en application hébergée.

Vous pouvez déployer un agent dans le même calcul d'IA attaché à son terrain de jeu ou à un autre calcul d'IA. Lorsque vous déployez les dernières modifications apportées à votre agent sur le calcul AI attaché, l'agent déployé représente un cliché de l'agent au moment du déploiement. Pour mettre à jour l'agent déployé vers la dernière version, vous devez redéployer l'agent.

Chaque agent dispose d'une URL de déploiement stable qui dépend de la clé d'agent unique. Le redéploiement multiple de l'agent écrase l'agent derrière l'URL de déploiement.

Le déploiement de vos agents présente les limites suivantes :

• Un agent ne peut être déployé que sur un seul cluster de calcul AI à un moment donné.
• Le déploiement du même agent plusieurs fois sur le même cluster de calcul AI écrase l'itération précédemment déployée de l'agent.

Une fois que vous avez déployé un agent, vous pouvez extraire l'URI de discussion pour émettre des requêtes par programmation et extraire les réponses de l'agent à partir de l'onglet Détails de l'agent.

L'URL endpoint est stable et est liée à chaque agent. L'URL inclut l'ID d'agent unique affecté à chaque agent. En d'autres termes, si vous annulez le déploiement d'un agent et que vous le déployez à nouveau, l'URL reste identique. L'avantage est que vous n'avez pas à modifier le code client appelant l'adresse, l'inconvénient est que vous pouvez écraser un agent en production.

L'URL présente la structure suivante :

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/{protocol}

où :

• oci-region correspond à la région d'instance AI Data Platform ;
• agentId est l'ID unique associé à l'agent.
• protocol est le protocole de communication : chat qui suit le format de l'API des réponses OpenAI et a2a qui suit le protocole de communication agent-agent. Les deux protocoles sont disponibles pour chaque adresse d'agent. Pour plus d'informations, reportez-vous à Déploiement d'agent A2A.

Remarques :

Deux calculs AI sont répertoriés dans l'onglet Détails. L'option Attaché à AI Compute permet de tester l'agent dans le playground de test. L'option Déployé sur AI Compute héberge l'agent déployé.

Le champ URL endpoint est renseigné après le déploiement de l'agent. Vous pouvez appeler cette URL d'adresse à partir de l'application de production.

Déployer un agent

Vous déployez les agents que vous avez créés et configurés afin que les autres utilisateurs puissent les voir et les utiliser dans votre instance AI Data Platform.

1. Sur la page d'accueil, accédez au dossier contenant l'agent à déployer.
2. En regard de l'agent, cliquez sur Actions, puis sur Déployer. Vous pouvez également cliquer sur le nom de l'agent, puis sur Déployer en haut à droite.
   
   

   

   
   
3. Sélectionnez le calcul AI à attacher à l'agent déployé.
4. Sélectionnez Pupitre AIDP pour le type d'autorisation.
5. Sélectionnez une stratégie de conservation des données de session.
   • Pour la période de conservation, indiquez le nombre de jours pendant lesquels les données de session sont conservées.
   • Pour Limite de taille de session, indiquez la taille maximale qu'une session peut atteindre.
   • Pour Limite de nombre de threads, indiquez le nombre maximal de threads de session conservés.
6. Cliquez sur Déployer.

Déployer un agent avec OAuth2

Vous pouvez déployer des agents que vous avez créés et configurés pour utiliser l'authentification OAuth2 afin de vous connecter à des fournisseurs d'identités externes.

1. Sur la page d'accueil, accédez au dossier contenant l'agent à déployer.
2. En regard de l'agent, cliquez sur Actions, puis sur Déployer. Vous pouvez également cliquer sur le nom de l'agent, puis sur Déployer en haut à droite.
   
   

   

   
   
3. Sélectionnez le calcul AI à attacher à l'agent déployé.
4. Sélectionnez OAuth2 pour le type d'autorisation.
5. Fournissez la demande d'audience. AI Data Platform Workbench renseigne automatiquement ce champ, mais vous pouvez le remplacer par une demande d'audience de votre fournisseur d'identités.
6. Fournissez la demande émetteur et l'URI d'extraction de JWKS. Ces informations proviennent de votre fournisseur d'identités.
7. Sélectionnez une stratégie de conservation des données de session.
8. Cliquez sur Déployer.

Appeler un agent déployé

Vous pouvez appeler l'URL endpoint de l'agent à partir de l'application de production.

Quelle que soit l'interface de programmation utilisée pour appeler l'adresse d'agent, vous devez être authentifié auprès d'OCI et disposer des droits d'accès appropriés. Dans le cas des adresses de flux d'agent, l'appelant doit disposer au moins du droit d'accès USE sur l'adresse d'agent.

L'URI endpoint est documenté dans l'onglet de détails de l'interface utilisateur de l'agent. Vous pouvez copier cet URI endpoint dans votre code pour appeler l'agent.

Méthodes d'appel des URI d'adresse

Vous pouvez appeler l'URI endpoint de l'agent via différents outils, kits SDK et interfaces de ligne de commande.

Les méthodes suivantes vous permettent d'appeler votre URI endpoint dans les agents Oracle AI Data Platform Workbench.

Appeler avec l'interface de ligne de commande OCI

L'exemple fourni montre comment utiliser l'interface de ligne de commande OCI et vous authentifier avec un jeton de sécurité. Remplacez <your-agent-flow-endpoint-uri> par l'URI d'adresse d'agent et <security_token> par le jeton de sécurité OCI.

oci raw-request
--http-method POST
--target-uri <your-agent-flow-endpoint-uri>
--request-body '{"query":"Tell me about the Ryder Cup in 1985"}'
--auth <security_token>

Appeler avec la bibliothèque de demandes Python

Vous pouvez utiliser le kit SDK Python OCI pour créer un signataire à authentifier auprès d'OCI. La bibliothèque de demandes Python peut être utilisée pour publier une demande sur l'URI endpoint de l'agent et renvoyer une réponse. L'exemple suivant montre comment utiliser le principal utilisateur via les fichiers de configuration et de clé privée OCI :

import oci import requests import json import uuid from contextlib import closing from requests import Request, Response
class AuthHelper: """ AuthHelper allows creating an OCI signer with either API key or security_token (which are short term sessions) """ def init(self, oci_profile: str, use_security_token:bool = True): config = oci.config.from_file(file_location="/Volumes/jr/default/misc/config",profile_name=oci_profile) if use_security_token: with open(config["security_token_file"], 'r') as f: token = f.read() private_key = oci.signer.load_private_key_from_file(config["key_file"])
 self.signer = oci.auth.signers.SecurityTokenSigner(token, private_key) else: self.signer = oci.signer.Signer( tenancy=config["tenancy"], user=config["user"], fingerprint=config["fingerprint"], private_key_file_location=config["key_file"], #pass_phrase=config.get("pass_phrase"), #private_key_content=config.get("key_content") )
@property
def Signer(self):
    return self.signer
 
class MyRawJsonRpcClient: """ Simple class using requests lib to post JSON to chat endpoint using OCI signing """ def init(self, chat_url:str, oci_profile: str, sessionKey:str, use_security_token:bool = True): self.authhelper = AuthHelper(oci_profile=oci_profile, use_security_token=use_security_token) self.authsigner = self.authhelper.Signer self.chat_url = chat_url self.sessionKey = sessionKey
def send(self, input:str) -> Response:
    body = {
        "isStreamEnabled" : False,
        "sessionKey" : self.sessionKey,
        "trace" : False,
        "input" :[{
            "role":"User",
            "content":[{
                "type" : "INPUT_TEXT",
                "text" : input                   
            }]
        }]
    }

    response:Request = requests.post(
        url =self.chat_url,
        params = None,
        auth = self.authsigner,
        json=body,
        headers={}
    )
    return response

Vous pouvez appeler l'URI d'adresse d'agent en instanciant la classe MyRawJsonRPCClient et en fournissant une valeur de profil OCI (trouvée dans le fichier de configuration OCI), l'URI d'adresse d'agent (chat_url) et une clé de session. Vous pouvez fournir n'importe quel élément sessionKey arbitraire. sessionKey est l'identificateur unique de la session utilisateur avec l'agent. Si vous continuez à réutiliser le même fichier sessionKey, les messages utilisateur et les réponses de l'agent sont ajoutés à la même conservation.

client = MyRawJsonRpcClient(chat_url="<your-agent-flow-endpoint-uri>",
   oci_profile = "DEFAULT",
   sessionKey= “<your-session-key>”,
   use_security_token = False )

Vous pouvez également fournir un message utilisateur et utiliser le client pour envoyer le message à l'URI endpoint de l'agent :

user_input = f"Hello, tell me a good dad joke."
r = client.send(input = user_input)
response_json = r.json()

via APEX

Vous pouvez utiliser l'exemple de code disponible dans le référentiel Github d'exemples AI Data Platform Workbench. Cet exemple vous guide tout au long du processus d'appel d'une adresse de déploiement d'agent à partir d'une application APEX.

Par Streamlit

Vous pouvez utiliser l'exemple de code disponible dans le référentiel Github d'exemples AI Data Platform Workbench. L'exemple vous guide tout au long du processus d'appel d'une adresse de déploiement d'agent à partir d'une application Streamlit.

Meilleures pratiques - Réponses asynchrones et non asynchrones

Nous vous recommandons d'écrire votre code client en supposant des réponses asynchrones. Exemple :

import httpx 
 
async def fetch_data(): 
    async with httpx.AsyncClient() as client: 
        response = await client.get(URL) 
        return response.json()

Annuler le déploiement d'un agent

Vous pouvez choisir d'annuler le déploiement des agents pour lesquels vous disposez des droits d'accès MANAGE, ce qui les rend indisponibles.

1. Dans la page d'accueil, accédez au dossier contenant l'agent dont vous souhaitez annuler le déploiement.
2. En regard de l'agent, cliquez sur Actions, puis sur Annuler le déploiement.
   
   

   

   
   
3. Cliquez sur Annuler le déploiement.

Surveiller les agents

Vous pouvez surveiller les détails relatifs aux sessions et aux mesures de vos agents pour voir les informations sur leur utilisation, les ressources qu'ils consomment, etc.

Votre agent comporte plusieurs onglets pour le suivi des détails d'utilisation, l'onglet Sessions, l'onglet Mesures et l'onglet Activité. Vous pouvez les trouver en haut du canevas de votre agent.

Traces et étendues

Les traces permettent d'observer vos agents en capturant et en affichant le flux des demandes d'agent. Les étendues sont les objets qui constituent une trace. Chaque étendue est une étape différente du flux, telle que les invites de discussion d'un utilisateur, les appels d'agent et les tâches de workflow.

Vous pouvez voir des traces pour la session en cours, l'exécution de test ou les sessions précédentes. Pour afficher la trace de la session en cours, accédez à l'onglet Flow et cliquez sur Playground. Le volet Détails en bas de la page affiche la trace de la session en cours dans le volet de gauche. Vous pouvez cliquer sur les objets de la trace pour les développer ou afficher des informations plus détaillées. Dans le volet de droite, vous pouvez cliquer sur les onglets Infos, Détails ou Evénements pour en savoir plus sur l'objet d'étendue sélectionné.

Vous pouvez voir les traces des sessions précédentes dans l'onglet Sessions en cliquant sur le nom de la session.

Sessions

Dans l'onglet Sessions, vous pouvez voir l'historique des sessions de cet agent. Vous pouvez voir si chaque session a réussi ou échoué, l'origine de l'URI, la date de démarrage de la session, la durée de la session et les jetons utilisés dans la session. Vous pouvez cliquer sur l'ID de session pour obtenir des détails plus spécifiques sur cette session et afficher des traces pour ces sessions spécifiques.

Vous pouvez filtrer les sessions affichées à l'aide de la barre de recherche pour filtrer par ID de session ou origine d'URI, à l'aide des filtres de date pour n'afficher qu'une plage de dates spécifique et du menu déroulant Statut de session pour filtrer selon qu'une session a réussi ou échoué.

Mesures

L'onglet Mesures affiche un récapitulatif des données d'utilisation pour toutes les sessions d'agent. La liste déroulante Plage de dates filtre la période que vous voulez voir résumée dans les cartes affichées. La sélection d'URI filtre la source de sélection d'URI pour laquelle vous voulez voir les détails. Vous pouvez modifier les cartes affichées et indiquer si elles incluent ou non des graphiques en tant que représentations visuelles de l'utilisation.

Activité

L'onglet Activité affiche un récapitulatif du statut de déploiement de l'agent. La colonne Opération indique le type d'opération de déploiement (Déployer ou Annuler le déploiement) et la colonne Statut indique le résultat de l'opération (Succès, Erreur, Avertissement, Echec). Vous pouvez voir qui a lancé l'opération et quand, ainsi que le message d'état associé au résultat de l'opération.

Afficher les sessions d'agent

Vous pouvez afficher un historique des sessions pour votre agent et filtrer les résultats pour afficher les tendances et faciliter le dépannage.

1. Sur la page d'accueil, accédez à votre agent.
2. Cliquez sur l'onglet Sessions.
3. Utilisez les filtres pour modifier les sessions affichées.

Visualiser les mesures d'agent

Vous pouvez visualiser les détails récapitulatifs de l'utilisation de l'agent, tels que l'utilisation des jetons, les durées de session, la latence, etc.

1. Sur la page d'accueil, accédez à votre agent.
2. Cliquez sur l'onglet Mesures.
3. Sélectionnez différentes options dans la liste déroulante Plage de dates pour voir l'écart entre les mesures et les calendriers.
4. Sélectionnez différentes options dans la liste déroulante Sélection d'URI pour filtrer les sources d'URI spécifiques.

Déplacer un agent

Vous pouvez déplacer les agents dont vous êtes propriétaire ou pour lesquels vous disposez des droits d'accès MANAGE.

1. Sur la page d'accueil, accédez au dossier contenant l'agent à déplacer.
2. En regard de l'agent à modifier, cliquez sur Actions, puis sur Déplacer.
3. Sélectionnez le nouvel emplacement de l'espace de travail pour l'agent. Cliquez sur Déplacer.

Copier un agent

Vous pouvez copier un agent que vous possédez ou pour lequel vous disposez des droits d'accès MANAGE sur un autre emplacement, un espace de travail disponible.

Vous pouvez copier des agents dans le même dossier ou dans un dossier différent. Les flux d'agent peuvent être copiés dans des dossiers de différents espaces de travail auxquels vous avez accès. La configuration de l'agent, ainsi que les paramètres d'outil et de garde-corps, sont copiés. Les attachements de cluster de calcul AI ne sont pas copiés et vous devez attacher l'agent à un nouveau cluster de calcul AI pour reprendre le développement.

1. Sur la page d'accueil, accédez au dossier contenant l'agent à déplacer.
2. En regard de l'agent à modifier, cliquez sur Actions, puis sur Copier vers l'espace de travail.
3. Indiquez un nouveau nom et une nouvelle description pour l'agent copié, si nécessaire.
4. Cliquez sur Parcourir et sélectionnez un nouvel emplacement dans l'espace de travail vers lequel copier l'agent. Cliquez sur Sélectionner.
5. Cliquez sur Copier.

Télécharger les fichiers d'agent

Vous pouvez télécharger les fichiers d'agent et leurs fichiers de garde-corps contenant les définitions de cet agent.

Les fichiers d'agent sont des fichiers JSON avec l'extension de fichier AFLOW et contiennent les définitions de votre agent. Les fichiers de garde-corps sont étiquetés _guardrails.JSON et contiennent les définitions de garde-corps de l'agent.

1. Accédez au dossier d'agent dans votre espace de travail.
2. Cliquez sur le nom de l'agent à télécharger.
   
   

   

   
   
3. En regard du fichier AFLOW de l'agent, cliquez sur Actions, puis sur Télécharger. Le fichier est téléchargé sur votre ordinateur local.
4. En regard du fichier _guardrails.JSON, cliquez sur Actions, puis sur Download (Télécharger). Le fichier est téléchargé sur votre ordinateur local.