Appeler un agent hébergé avec l’interface CLI Azure développeur

Permet azd ai agent invoke d’envoyer des messages à votre agent, soit la version déployée dans Microsoft Foundry, soit une instance en cours d’exécution locale. Vous découvrez comment choisir un agent, utiliser des points de terminaison directs, gérer des sessions, envoyer des fichiers, épingler des versions et inspecter les réponses brutes.

Prerequisites

Appeler l’agent déployé

  • Envoyez une invite à l’agent déployé :

    azd ai agent invoke "What is Microsoft Foundry?"

Appeler un agent spécifique

  • Si votre projet contient plusieurs agents, spécifiez celui à appeler :

    azd ai agent invoke my-agent "What is Microsoft Foundry?"

Appeler un point de terminaison spécifique déployé

Lorsque vous souhaitez appeler un agent déployé spécifique sans dépendre de l’environnement azd actif ou azure.yaml, utilisez cette option --agent-endpoint pour pointer directement à l’URL de l’agent déployé. Ce modèle est utile à partir d’un script en dehors du projet, d’un agent de codage ou lorsque vous testez une version spécifique de l’agent.

  • Transmettre le point de terminaison de l’agent déployé :

    azd ai agent invoke \
   --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
   "Summarize today's release notes."

    --agent-endpoint remplace l’environnement azd et azure.yaml la résolution azd. Vous n’avez donc pas besoin d’être à l’intérieur d’un répertoire de projet azd pour l’utiliser.

Exécuter localement

  • Appelez un agent local :

    azd ai agent invoke --local "Hello!"

    L’agent doit déjà être lancé avec azd ai agent run dans un autre terminal.

Appeler sur un port local personnalisé

  • Si votre agent s’exécute sur un port autre que par défaut, passez --port:

    azd ai agent invoke --local --port 9090 "Hello!"

Choisir un protocole

Le protocole utilisé pour l’appel est déterminé par le protocols champ du azure.ai.agent service dans azure.yaml.

  • responses -- envoie une requête d’API Réponses OpenAI standard avec {"input": "your message"}. L’historique des conversations est géré automatiquement.
  • invocations - envoie la charge utile attendue par votre code d’agent. Utilisez --input-file (-f) avec un fichier JSON correspondant au schéma que votre gestionnaire définit.

Pour les agents invocations, consultez le fichier README de l’exemple ou inspectez le point d’entrée du gestionnaire pour comprendre la charge utile attendue.

  • Si votre agent implémente plusieurs protocoles, passez --protocol (-p) pour choisir :

    azd ai agent invoke --protocol invocations -f request.json

Gérer les sessions

Les sessions sont conservées pour chaque agent. Lorsque vous appelez un agent, azd enregistre l’ID de session localement afin que la prochaine invoke continue automatiquement la même session et gère l’historique des conversations entre les appels.

Démarrer une nouvelle session

  • Supprimez la session enregistrée et recommencez à zéro :

    azd ai agent invoke --new-session "Start fresh"

Utiliser un ID de session spécifique

  • Transmettez un ID de session existant :

    azd ai agent invoke --session-id my-session-123 "Continue conversation"

Envoyer un fichier en tant qu’entrée

Pour les charges utiles structurées ou volumineuses, en particulier avec le invocations protocole, passez un fichier JSON.

  1. Envoyer un fichier :

    azd ai agent invoke -f request.json

  2. Ou envoyez un fichier à un agent spécifique :

    azd ai agent invoke my-agent -f request.json

Appeler une version déployée

Lorsqu’un agent a plusieurs versions déployées, épinglez-en une spécifique avec --version. azd crée ou réutilise une session sauvegardée par cette version, afin que chaque version conserve son propre état de conversation.

  • Épingler une version :

    azd ai agent invoke --version 3 "Use the v3 prompt"

    --version ne peut pas être combiné avec --local ou --session-id, car les sessions sont liées à une version lorsqu’elles sont créées.

Définir un délai d’expiration personnalisé

  • Indiquez un délai d’expiration en secondes :

    azd ai agent invoke --timeout 300 "Process this large dataset"

    Le délai d’expiration par défaut est de 1800 secondes (30 minutes). Utilisez --timeout 0 pour indiquer aucune expiration.

Transmettre des clés d’isolation

Les agents configurés avec l’isolation basée sur l’en-tête Foundry nécessitent des clés par utilisateur ou par conversation sur chaque requête. Transmettre-les avec --user-isolation-key et --chat-isolation-key.

  • Transmettez des clés d’isolation dans la requête :

    azd ai agent invoke \
   --user-isolation-key "$USER_KEY" \
   --chat-isolation-key "$CHAT_KEY" \
   "Hello!"

Pour le modèle complet, notamment la façon dont les sessions, les fichiers et les commandes de surveillance utilisent les mêmes indicateurs, consultez Passer des clés d’isolation à un agent hébergé.

Inspecter la réponse HTTP brute

Lorsque vous devez voir exactement ce que le serveur a retourné, y compris les en-têtes de réponse tels que la version de l’agent, la ligne d’état et le corps non modifié, passer --output raw (-o raw).

  • Demande de sortie brute :

    azd ai agent invoke --output raw "Hello!"

    En mode brut, les lignes récapitulatives conviviales comme Session: et Invocation: sont supprimées et la réponse HTTP est vidée en détail. Ce mode est utile pour déboguer le comportement du serveur et confirmer la version de l’agent qui a géré l’appel.

Contenu connexe

  • Last updated on