Utiliser azd ai avec des agents de codage et des scripts

Utilisez azd ai depuis des agents de codage et des scripts avec le même comportement que celui que les humains obtiennent sur un terminal. Vous définissez un contexte autonome, désactivez les invites, analysez la sortie JSON et appelez des points de terminaison directs de l’agent pour une automatisation fiable.

Prerequisites

• Les extensions azd Foundry installées.
• Une session authentifiée azd .
• Point de terminaison de projet Microsoft Foundry pour les commandes que vous souhaitez exécuter. Pour plus d’informations, consultez Définir le contexte du projet azd.
• Facultatif : un agent hébergé déjà déployé lorsque vous devez appeler le point de terminaison d’un agent. Pour la configuration, consultez Déployer un agent hébergé.

Commencez par la compétence Microsoft Foundry

Les agents de codage fonctionnent mieux lorsqu’ils connaissent déjà les azd ai conventions. La compétence Microsoft Foundry fournit à un agent de codage cette connaissance : elle génère des commandes correctes azd ai et un câblage Foundry, et applique les pratiques de cet article : définition du contexte du projet, passage --no-promptet demande des --output json résultats structurés. Dirigez d’abord votre agent de codage vers la compétence, puis utilisez les schémas présentés dans le reste de cet article pour examiner et fiabiliser ce qu’il produit.

Définir le contexte du projet une fois

Chaque commande de ressources, telle que connection, toolbox, skill ou routine, nécessite un point de terminaison de projet Foundry à cibler. Dans l’automatisation, définissez ce point de terminaison une fois par session, travail CI ou appel d’agent de codage, puis utilisez-le pour le reste de l’exécution.

Il existe deux modèles.

Épinglez une seule fois avec azd ai project set

Lorsque vous souhaitez que le contexte persiste entre les interpréteurs de commandes sans exporter une variable d’environnement, définissez-le dans la configuration globale :

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt
azd ai project show

azd ai project set <endpoint> n’est pas entièrement interactif lorsque vous connaissez déjà l’URL. azd ai project show indique quelle source a déterminé le point de terminaison actif. Utilisez-la en haut d’une session si vous n’êtes pas sûr de l’état dans lequel se trouve l’hôte.

Définir une variable d’environnement

Définissez FOUNDRY_PROJECT_ENDPOINT dans l’environnement où votre script ou votre agent de codage s’exécute. Chaque commande azd ai le prend automatiquement en compte après l’environnement azd du projet et la configuration globale.

export FOUNDRY_PROJECT_ENDPOINT="https://my-project.services.ai.azure.com/api/projects/my-project"
azd ai connection list --output json

Ce modèle se prête bien à l’intégration continue (CI), car les secrets et la configuration sont généralement déjà fournis sous forme de variables d’environnement, et il n’y a pas d’état global à nettoyer entre les jobs.

Pour obtenir une explication complète de la façon dont l’interface CLI résout le point de terminaison, y compris l’ordre de priorité, consultez Définir le contexte du projet azd.

Désactiver les invites

Chaque azd ai commande accepte --no-prompt. Lorsque vous la définissez, la commande échoue rapidement au lieu de bloquer l’entrée interactive. Un argument obligatoire manquant ou une demande de confirmation delete qui, autrement, attendrait un appui sur une touche devient une erreur immédiate avec une sortie au format structuré.

Définissez toujours --no-prompt en CI et dans les invocations de l’agent de codage.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --no-prompt

Obtenir la sortie JSON

La plupart des commandes azd ai prennent en charge --output json, y compris les commandes de ressource connection, toolbox, skill et routine, ainsi que azd ai agent show. Utilisez-le pour analyser le résultat de manière fiable avec jq, ConvertFrom-Json ou l’analyseur JSON de votre langage, au lieu d’extraire la sortie textuelle lisible par un humain. La commande azd ai agent invoke utilise --output raw pour la réponse non modifiée du serveur.

# List connections, extract names with jq
azd ai connection list --output json | jq -r '.[].name'

# Show a single resource as JSON
azd ai routine show daily-digest --output json | jq '.trigger'

# PowerShell example
$conn = azd ai connection show my-search --output json | ConvertFrom-Json
Write-Host $conn.target

Le texte produit est destiné à être lu par des humains et peut changer d’une version à l’autre. La structure JSON constitue le contrat stable.

Créer des ressources de manière idempotente

create n’est pas un upsert. Si la ressource nommée existe déjà, une nouvelle exécution échoue. Cette valeur par défaut fonctionne bien pour les ressources partagées au niveau du projet, car elle empêche un appelant de remplacer silencieusement l’état d’un autre appelant.

Pour l’automatisation qui doit réussir quel que soit l’état antérieur, les connection commandes acceptent --force de remplacer la ressource existante.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --force --no-prompt

Si vous n’avez besoin de modifier que quelques champs et que vous souhaitez conserver tout le reste, utilisez update. Ou utilisez les sous-commandes de la collection dédiée, comme tool, tag, metadata et key.

Créer une boîte à outils à partir d’un fichier

Pour une boîte à outils à entrées multiples qui regroupe des outils, des connexions et des compétences intégrés, placez la définition complète dans un fichier YAML et transmettez --from-file à azd ai toolbox create. Le fichier utilise la forme AgentSchema correspondante.

azd ai toolbox create research --from-file ./resources/research-toolbox.yaml --no-prompt

--from-file est une entrée à lecture unique lue lors de l’invocation. L’interface CLI n’effectue pas le suivi ou la réécriture du fichier. Par conséquent, les modifications ultérieures de YAML n’ont aucun effet tant que vous n’avez pas réexécuté la commande. Créez des connexions avec des indicateurs explicites (--kind, --target, --auth-typeet les indicateurs d’informations d’identification correspondants), puis référencez-les par nom à partir du fichier de boîte à outils.

Appeler un agent déployé sans projet azd

Lorsqu’un agent de codage ou un script doit appeler un agent déployé qui se trouve en dehors de son répertoire de travail, utilisez-le --agent-endpoint pour le cibler directement. Cette approche contourne à la fois azure.yaml et l’environnement azd actif. L’URL seule est suffisante.

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." \
  --no-prompt

Utilisez cette configuration lorsque l’intégration continue d’un dépôt doit appeler un agent géré par un autre dépôt, ou lorsqu’un serveur MCP sert d’interface à plusieurs agents et ne connaît que les URL de leurs points de terminaison. Pour obtenir l’ensemble complet d’options invoke , consultez Appeler un agent hébergé.

Transmettre des secrets à une exécution en local

Pour démarrer l’agent localement avec des secrets, définissez-les en tant que variables d’environnement azd et faites-y référence dans le mappage env de votre service azure.ai.agent dans azure.yaml. Les valeurs se trouvent dans .azure/<env>/.env, qui est ignoré par Git par défaut.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

# azure.yaml
services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

Pour les secrets qui ne doivent pas être stockés dans un fichier local .env, stockez-les dans une connexion de projet Foundry et faites-y référence à l’aide d’un espace réservé ${{connections.<name>.credentials.<field>}}. Consultez Exécuter un agent hébergé localement pour la surface d’exécution locale complète.

Scripter une courte configuration

Ce script bash combine les modèles ci-dessus. Il fixe le contexte du projet, crée de manière idempotente une connexion et une boîte à outils, intègre un outil dans la boîte à outils et vérifie le résultat en analysant le JSON.

#!/usr/bin/env bash
set -euo pipefail

azd ai project set "$FOUNDRY_PROJECT_ENDPOINT" --no-prompt

# A 'remote-tool' connection holds the URL and credentials for the MCP server.
azd ai connection create tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys \
  --custom-key "x-api-key=$TAVILY_KEY" \
  --force --no-prompt

# Create the toolbox with the connection wired in, in a single shot
cat > research-toolbox.yaml <<'EOF'
description: Research tools
connections:
  - name: tavily
EOF

azd ai toolbox create research --from-file ./research-toolbox.yaml --no-prompt

echo "Toolbox state:"
azd ai toolbox connection list research --output json | jq .

set -euo pipefail garantit que le script échoue rapidement en cas d’erreur d’étape. Combiné avec --no-prompt, qui vous donne un code de sortie déterministe adapté aux portes CI.

Vérifier la résolution du point de terminaison

Les agents de codage peuvent prédire le projet Foundry qu’une commande cible en marchant dans cet ordre de priorité. La première source qui génère une valeur gagne ; les sources ultérieures ne sont pas consultées.

1. indicateur --project-endpoint (ou -p) (toujours prioritaire).
2. Dans un projet azd : la valeur active de azd env.
3. Configuration globale (définie par azd ai project set).
4. La variable d’environnement FOUNDRY_PROJECT_ENDPOINT.
5. Erreur comportant une suggestion structurée pour exécuter azd ai project set ou fournir --project-endpoint.

Pour obtenir une explication complète, notamment la façon dont le contexte autonome interagit avec le travail dans le projet, consultez Définir le contexte du projet azd.

Appliquer les conseils de l’agent de codage

• Passez toujours --no-prompt, et ajoutez --output json aux commandes qui le prennent en charge. Ensemble, ils vous donnent un code de sortie prévisible ainsi qu’un résultat analysable.
• Vérifiez le contexte déterminé avec azd ai project show au début d’une session si vous ne savez pas avec certitude dans quel état se trouve l’hôte. C’est un appel en lecture seule bon marché.
• En cas d’échec, préférez analyser la suggestion structurée dans la sortie d’erreur pour décider des étapes suivantes. Par exemple, une erreur « Point de terminaison de projet No Foundry résolu » implique que vous devez exécuter azd ai project set, ou définir FOUNDRY_PROJECT_ENDPOINT, avant de réessayer.
• Utilisez --debug uniquement lors du diagnostic d’un problème. Il produit une sortie détaillée et multiligne difficile à analyser et qui n’a jamais été destinée à être une interface programmatique.
• Traitez les échecs create avec « already exists » comme des erreurs récupérables. Relancez avec --force si la ressource vous appartient et que vous souhaitez la remplacer, ou passez à update et aux sous-commandes de la collection si vous n’avez besoin d’en modifier qu’une partie.

Contenu connexe

• Définissez le contexte de projet azd pour comprendre comment l’interface CLI résout le point de terminaison du projet Foundry.
• Configurez CI/CD pour les agents hébergés avec l’interface CLI de développeur Azure pour les modèles qui s’exécutent azd ai dans des pipelines.
• Appelez un agent hébergé pour obtenir des options complètes azd ai agent invoke , notamment --agent-endpoint.