Inscrire et gérer des agents personnalisés

Microsoft Plan de contrôle Foundry fournit une gestion centralisée et une observabilité pour les agents qui s’exécutent sur différentes plateformes et infrastructures. Cet article traite des données de gestion et de diagnostic pour les agents personnalisés existants.

Pour connaître les étapes de transition, consultez Migrer des agents personnalisés vers des agents externes.

Conditions préalables

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

• Agent personnalisé existant inscrit dans Foundry Control Plane.

• La passerelle IA existante configurée dans votre ressource Foundry et le point de terminaison back-end accessible de l’agent.

Ajouter un agent personnalisé

Vous ne pouvez plus ajouter un nouvel agent personnalisé dans Foundry Control Plane. Pour une nouvelle intégration, inscrivez un agent externe. Pour un agent personnalisé existant, suivez le guide de migration.

Architecture d’agent personnalisée existante

Les agents personnalisés existants utilisent API Management comme proxy pour les communications avec l’agent, afin qu’il puisse contrôler l’accès et surveiller l’activité.

Connecter des clients à l’agent

Un enregistrement d’agent personnalisé existant a une URL de passerelle que les clients peuvent utiliser. Étant donné que la passerelle agit comme proxy pour les communications avec votre agent, elle peut contrôler l’accès et surveiller l’activité. Continuez à utiliser cette URL pendant la migration vers l’inscription auprès d’un agent externe.

Pour rechercher l’URL de passerelle existante :

1. Dans la liste des agents, sélectionnez le bouton radio en regard du nom de l’agent personnalisé pour ouvrir le volet d'informations. Ne sélectionnez pas le nom de l’agent lui-même, car ce lien s’éloigne du volet Ressources .

2. Dans le volet d’informations, sous URL de l’agent, sélectionnez l’option Copier .

   

3. Continuez à utiliser cette URL de passerelle pour appeler l’agent.

Dans cet exemple, les clients utilisent le Kit de développement logiciel (SDK) LangGraph et l’URL de passerelle existante pour appeler un agent LangGraph. Ce code crée un thread, envoie un message demandant la météo et diffuse la réponse.

import asyncio
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)

asyncio.run(stream_run())

Sortie attendue : l’agent traite le message et diffuse des réponses en tant que blocs. Chaque bloc contient des résultats partiels de l’exécution de l’agent. Ces résultats peuvent inclure des appels d’outils à la fonction météo et la réponse finale concernant la météo à Los Angeles.

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 :

1. Dans la barre d’outils, sélectionnez Utiliser.

2. Dans le volet gauche, sélectionnez Ressources.

3. Sélectionnez le bouton radio en regard de l’agent que vous souhaitez bloquer. Le volet d’informations s’affiche. Ne sélectionnez pas le nom de l’agent, car ce lien quitte le volet Ressources .

4. Sélectionnez Mettre à jour l’état, puis sélectionnez Bloquer.

   

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

1. Sélectionnez Mettre à jour l’état, puis débloquer.

2. 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 projet a configuré Application Insights, Foundry journalise les demandes dans Application Insights par défaut. Foundry utilise également ces données pour calculer :

• Exécutions
• 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 journaux envoyés à Foundry

1. Dans la barre d’outils, sélectionnez Utiliser.

2. Dans le volet gauche, sélectionnez Ressources.

3. Sélectionnez le bouton radio à côté de l’agent pour ouvrir le panneau d'informations. Ne sélectionnez pas le nom de l’agent, car ce lien quitte le volet Ressources .

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

   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 le Agent Protocol 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 permet à Foundry d’accéder à 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, suivez les instructions de Connect Application Insights à votre projet Foundry.

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 .

Solutions de plateformes instrumentales

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 chaîne de connexion. 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 :

Contenu connexe

• Migrer les agents personnalisés vers les agents externes
• Quel est le plan de contrôle Microsoft Foundry ?
• Surveiller l’intégrité et les performances de l’agent dans votre flotte