Inscrire et gérer des agents personnalisés

Le plan de contrôle Microsoft Foundry fournit une gestion centralisée et une observabilité pour les agents qui s’exécutent sur différentes plateformes et infrastructures. Vous pouvez inscrire des agents personnalisés qui s’exécutent dans Azure services de calcul ou d’autres environnements cloud pour obtenir une visibilité sur leurs opérations et contrôler leur comportement.

Cet article explique comment inscrire un agent personnalisé dans Le plan de contrôle Foundry. Vous découvrez comment configurer votre agent pour l’inscription, configurer la collecte de données et utiliser les fonctionnalités de gestion du plan de contrôle Foundry.

Prerequisites

Un compte Azure avec un abonnement actif. Si vous n'en avez pas, créez un compte Azure gratuit, qui inclut un abonnement d'essai gratuit.
Un projet Foundry. Si vous n'en avez pas, créez un projet.

Une passerelle IA configurée au sein de votre ressource Foundry. Foundry utilise Azure API Management pour inscrire des agents en tant qu’API.
Agent que vous déployez et exposez via un point de terminaison accessible. Le point de terminaison peut être un point de terminaison public ou un point de terminaison accessible à partir du réseau où vous déployez la ressource Foundry.

Note

Cette fonctionnalité est disponible uniquement dans le portail Foundry (nouveau). Recherchez dans la bannière du portail pour confirmer que vous utilisez Foundry (nouveau).

Ajouter un agent personnalisé

Vous pouvez inscrire un agent personnalisé dans le plan de contrôle Foundry. Développez l’agent dans la technologie de votre choix, pour les solutions de plateforme et d’infrastructure.

Lorsque vous inscrivez un agent personnalisé, Foundry utilise API Management pour agir en tant que proxy pour les communications avec votre agent, afin qu’il puisse contrôler access et surveiller l’activité.

Le diagramme suivant montre l’architecture résultante lorsque vous inscrivez un agent personnalisé.

Vérifier votre agent

Vérifiez que votre agent répond aux exigences d’inscription :

Votre agent expose un point de terminaison exclusif.
Le réseau sur lequel vous déployez la ressource Foundry peut atteindre le point de terminaison de l’agent.
L’agent communique à l’aide de l’un des protocoles pris en charge : HTTP (général) ou A2A (plus spécifique).
Votre agent émet des données à l’aide des conventions sémantiques OpenTelemetry pour les solutions d’INTELLIGENCE artificielle générative (ou vous n’avez pas besoin de cette fonctionnalité).
Vous pouvez configurer le point de terminaison que les utilisateurs utilisent pour communiquer avec l’agent. Une fois que vous avez inscrit un agent, Le plan de contrôle Foundry génère une nouvelle URL. Les clients et les utilisateurs doivent utiliser cette URL pour communiquer avec l’agent.

Préparer votre project Foundry

Avant d’inscrire l’agent personnalisé que vous avez ajouté à un project Foundry, assurez-vous que vous avez correctement configuré le project :

Connectez-vous à Microsoft Foundry. Assurez-vous que l'interrupteur New Foundry est activé. Ces étapes font référence à Foundry (nouveau).
Vérifiez qu’une passerelle IA est configurée dans votre project :
1. Dans la barre d’outils, sélectionnez Utiliser.
2. Dans le volet gauche, sélectionnez Administrateur.
3. Ouvrez l’onglet Passerelle IA .
4. Le volet répertorie toutes les passerelles IA configurées et mappées à une ressource Foundry. Vérifiez si la ressource Foundry que vous souhaitez utiliser a une passerelle IA associée.
5. Si la ressource Foundry que vous souhaitez utiliser n’a pas de passerelle IA configurée (elle n’est pas répertoriée), ajoutez-en une à l’aide de l’option Ajouter une passerelle IA .
  
  Une passerelle IA est gratuite pour configurer et déverrouiller de puissantes fonctionnalités de gouvernance telles que la sécurité, les données de diagnostic et les limites de débit pour vos agents, outils et modèles. Pour plus d’informations, consultez Créer une passerelle IA.
Vérifiez que vous disposez de l'observabilité configurée dans le projet. Le plan de contrôle Foundry utilise la ressource Application Insights associée à votre projet sélectionné pour émettre des données facilitant le diagnostic de votre agent.
1. Dans la barre d’outils, sélectionnez Utiliser.
2. Dans le volet gauche, sélectionnez Administrateur.
3. Sous All projects, utilisez la zone de recherche pour rechercher votre project.
4. Sélectionnez le project.
5. Sélectionnez l’onglet Ressources connectées .
6. Vérifiez qu’il existe une ressource associée dans la catégorie AppInsights .
7. S’il n’existe aucune ressource associée, ajoutez-en une en sélectionnant Ajouter une connexion>Application Insights.

Votre project est configuré pour l’observabilité et le suivi.

Inscrire l’agent

Dans la barre d’outils, sélectionnez Utiliser.
Dans le volet Vue d’ensemble , sélectionnez Inscrire l’agent.

L’Assistant Inscription s’affiche. Tout d’abord, renseignez les détails sur l’agent que vous souhaitez inscrire. Les propriétés suivantes décrivent l’agent au fur et à mesure qu’il s’exécute sur sa plateforme :

Propriété	Descriptif	Obligatoire
URL de l’agent	Point de terminaison (URL) dans lequel votre agent s’exécute et reçoit des demandes. En général, mais en fonction de votre protocole, vous indiquez l’URL de base que vos clients utilisent. Par exemple, si votre agent utilise l’API OpenAI Chat Completions, vous indiquez `https://<host>/v1/` sans `/chat/completions` car les clients l’ajoutent généralement.	Oui
Protocole	Protocole de communication pris en charge par votre agent. Utilisez HTTP en général. Ou si votre agent prend en charge plus spécifiquement A2A, indiquez-le.	Oui
URL de la carte de l’agent A2A	Chemin d’accès à la spécification JSON de la carte d’agent. Si vous ne le spécifiez pas, le système utilise la valeur par défaut `/.well-known/agent-card.json`.	Non
ID de l’agent OpenTelemetry	ID d’agent que votre agent utilise pour émettre des traces en fonction des conventions sémantiques OpenTelemetry pour l’IA générative. Les traces en font état dans l’attribut `gen_ai.agents.id` pour les intervalles associés à l’opération nommée `create_agent`. En l’absence de cette valeur, le système s’appuie sur la valeur Nom de l’agent afin de localiser les traces et les journaux d’activité générés par ce nouvel agent.	Non
URL du portail d’administration	URL du portail d’administration dans laquelle vous pouvez effectuer d’autres opérations d’administration pour cet agent. Foundry peut stocker cette valeur pour des raisons pratiques. Foundry n'a aucun accès pour initier des opérations directement sur ce portail.	Non

Configurez l’affichage de l’agent dans le plan de contrôle Foundry :

Propriété	Descriptif	Obligatoire
Project	Le project où vous inscrivez l’agent. Foundry utilise la passerelle IA configurée dans la ressource qui contient le projet pour configurer le point de terminaison entrant vers l’agent. Vous pouvez sélectionner uniquement les projets qui ont une passerelle IA activée parmi leurs ressources. Si vous ne voyez aucune passerelle IA, configurez une passerelle IA dans votre ressource Foundry. Nous vous recommandons également de configurer Application Insights dans la project sélectionnée. Foundry utilise la ressource Application Insights du projet comme point de collecte des traces et des journaux d’activité.	Oui
Nom de l’agent	Nom de l’agent que vous souhaitez qu’il apparaisse dans Foundry. Le système peut également exploiter ce nom pour identifier les traces et journaux d’activité pertinents dans Application Insights si aucune valeur différente n’est définie pour l’ID de l’agent OpenTelemetry.	Oui
Description	Description claire de cet agent.	Non

Enregistrez les modifications.
Foundry ajoute le nouvel agent. Pour vérifier la liste des agents, sélectionnez Ressources dans le volet gauche.
Pour afficher uniquement les agents personnalisés, utilisez le filtre source et sélectionnez Personnalisé.

Connecter des clients à l’agent

Lorsque vous inscrivez votre agent dans Foundry, vous obtenez une nouvelle URL pour que vos clients utilisent. Étant donné que Foundry agit comme proxy pour les communications avec votre agent, elle peut contrôler l'accès et surveiller l'activité.

Pour distribuer la nouvelle URL afin que vos clients puissent appeler l’agent :

Sélectionnez l’agent personnalisé.
Dans le volet d’informations, sous URL de l’agent, sélectionnez l’option Copier .
Utilisez la nouvelle URL pour appeler l’agent au lieu du point de terminaison d’origine.

Dans cet exemple, vous déployez un agent LangGraph. Les clients utilisent le Kit de développement logiciel (SDK) LangGraph pour l’utiliser. Le client utilise la nouvelle valeur d’URL de l’agent . Ce code crée un thread, envoie un message demandant la météo et diffuse la réponse.

from langgraph_sdk import get_client

client = get_client(url="https://apim-my-foundry-resource.azure-api.net/my-custom-agent/") 

async def stream_run():
   thread = await client.threads.create()
   input_data = {"messages": [{"role": "human", "content": "What's the weather in LA?"}]}
   
   async for chunk in client.runs.stream(thread['thread_id'], assistant_id="your_assistant_id", input=input_data):
       print(chunk)

Sortie attendue : l’agent traite le message et diffuse des réponses en tant que blocs. Chaque segment présente des résultats partiels issus de l’exécution de l’agent. Ces résultats peuvent comprendre des appels d’outils vers la fonction météo ainsi que la réponse finale relative à la météo à Los Angeles.

Note

Bien que Foundry agisse comme proxy pour les demandes entrantes pour votre agent, le schéma d’autorisation et d’authentification d’origine dans le point de terminaison d’origine s’applique toujours. Lorsque vous utilisez le nouveau point de terminaison, fournissez le même mécanisme d’authentification que si vous utilisez le point de terminaison d’origine.

Bloquer et débloquer l’agent

Pour les agents personnalisés, Foundry n'a pas accès à l'infrastructure sous-jacente où l'agent s'exécute. Les opérations de démarrage et d'arrêt ne sont donc pas disponibles. Toutefois, Foundry peut bloquer les demandes entrantes adressées à l’agent afin que les clients ne puissent pas l’utiliser. Cette fonctionnalité permet aux administrateurs de désactiver un agent s’il se comporte mal.

Pour bloquer les demandes entrantes à votre agent :

Dans la barre d’outils, sélectionnez Utiliser.
Dans le volet gauche, sélectionnez Ressources.
Sélectionnez l’agent que vous souhaitez bloquer. Le volet d’informations s’affiche.
Sélectionnez Mettre à jour l’état, puis sélectionnez Bloquer.
Confirmez l’opération.

Après avoir bloqué l’agent, la valeur d’état de l’agent dans Foundry est bloquée. Les agents dans l’état bloqué s’exécutent dans leur infrastructure associée, mais ne peuvent pas prendre de demandes entrantes. Foundry bloque toute tentative d’interface avec l’agent.

Pour débloquer l’agent :

Sélectionnez Mettre à jour l’état, puis débloquer.
Confirmez l’opération.

Activer les données de diagnostic pour l’agent

Foundry utilise la norme open OpenTelemetry pour comprendre ce que font les agents. Si votre project a configuré Application Insights, Foundry journalise les demandes dans Application Insights par défaut. Foundry utilise également ces données pour calculer :

Runs
Taux d’erreur
Utilisation (si disponible)

Pour obtenir le meilleur niveau de fidélité, Foundry s’attend à ce que les agents personnalisés respectent les conventions sémantiques pour les solutions d’IA génératives dans la norme OpenTelemetry.

Afficher les traces et les logs envoyés à Foundry

Dans la barre d’outils, sélectionnez Utiliser.
Dans le volet gauche, sélectionnez Ressources.
Sélectionnez l’agent.
La section Traces affiche une entrée pour chaque appel HTTP effectué au point de terminaison de l’agent.

Pour afficher les détails, sélectionnez une entrée.

Conseil / Astuce

Dans cet exemple, vous pouvez voir comment les clients utilisent le point de terminaison du nouvel agent pour communiquer avec l’agent. L’exemple montre un agent servi avec l'Agent Protocol à partir de LangChain. Les clients utilisent l’itinéraire /runs/stream.

Dans cet exemple, la trace n’inclut aucun détail au-delà du billet HTTP. Le code de l’agent n’inclut pas d’instrumentation supplémentaire. Dans la section suivante, vous allez apprendre à instrumenter votre code et à obtenir des détails tels que les appels d’outils et les appels LLM (Large Language Model).

Instrumenter des agents de code personnalisés

Si vous générez votre agent à l’aide de code personnalisé, instrumentez votre solution pour émettre des traces conformément à la norme OpenTelemetry et les envoyer à Application Insights. L’instrumentation donne à Foundry accès à des informations détaillées sur ce que fait votre agent.

Envoyez des traces à la ressource Application Insights de votre projet à l’aide de sa clé d’instrumentation. Pour obtenir la clé d’instrumentation associée à votre projet, veuillez suivre les instructions de la rubrique Activez le traçage dans votre projet.

Dans cet exemple, vous configurez un agent développé avec LangGraph pour émettre des traces dans la norme OpenTelemetry. Le traceur capture toutes les opérations de l’agent, y compris les appels d’outils et les interactions de modèle. Le traceur envoie ensuite les opérations à Application Insights pour la surveillance.

Ce code utilise le package langchain-azure-ai. Pour obtenir des conseils sur l’instrumentation de solutions spécifiques avec OpenTelemetry, en fonction du langage de programmation et de l’infrastructure utilisés par votre solution, consultez les API de langage et les kits SDK.

pip install -U langchain-azure-ai[opentelemetry]

Ensuite, instrumentez votre agent :

from langchain.agents import create_agent
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

application_insights_connection_string = 'InstrumentationKey="12345678...'

tracer = AzureAIOpenTelemetryTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.1",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
).with_config({ "callbacks": [tracer] })

Sortie attendue : l’agent s’exécute normalement lors de l’émission automatique de traces OpenTelemetry vers Application Insights. Les traces incluent les noms des opérations, les durées, les appels de modèle, les appels d’outils et l’utilisation des jetons. Vous pouvez afficher ces traces dans le portail Foundry, dans la section Traces .

Conseil / Astuce

Vous pouvez transmettre le connection string à Application Insights à l’aide de la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING.

Solutions de plateforme d'instrumentation

Si votre agent s’exécute sur une solution de plateforme qui prend en charge OpenTelemetry, mais ne prend pas en charge Application Insights, déployez un collecteur OpenTelemetry et configurez votre logiciel pour envoyer des données OTLP au collecteur (configuration OpenTelemetry standard).

Configurez le collecteur avec l’exportateur Azure Monitor pour transférer des données vers Application Insights à l’aide de votre connection string. Pour plus d’informations sur la façon de l’implémenter, consultez Configure Azure Monitor OpenTelemetry.

Dépannage des traces

Si vous ne voyez pas de traces, vérifiez les éléments suivants :

L’project où vous inscrivez votre agent a configuré Application Insights. Si vous avez configuré Application Insights après avoir inscrit l’agent personnalisé, vous devez annuler l’inscription de l’agent et l’inscrire à nouveau. La configuration d’Application Insights n’est pas automatiquement mise à jour après l’inscription si vous l’avez modifiée.
Vous avez configuré l'agent (en cours d'exécution sur son infrastructure) pour envoyer des traces à Application Insights, et vous utilisez la même ressource Application Insights que celle utilisée par votre project.
L’instrumentation est conforme aux conventions sémantiques OpenTelemetry pour l’IA générative.
Les traces incluent des étendues avec des attributs operation="create_agent" et gen_ai.agents.id="<agent-id>" (ou gen_ai.agents.name="<agent-id>"). Dans ce dernier attribut, "<agent-id>" est la valeur d’ID de l’agent OpenTelemetry que vous avez configurée lors de l’inscription.

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-03-11