Uso de azd ai con agentes de codificación y scripts

Utiliza azd ai de agentes de programación y scripts con el mismo comportamiento que obtienen los humanos en un terminal. Configuras un contexto autónomo, desactivas las solicitudes, analizas la salida JSON e invocas puntos de conexión directos del agente para una automatización fiable.

Prerequisites

• Las extensiones de azd Foundry instaladas.
• Una sesión autenticada azd .
• Un punto de conexión de proyecto de Microsoft Foundry para los comandos que desea ejecutar. Para obtener más información, vea Establecer el contexto del proyecto azd.
• Opcional: un agente hospedado e implementado cuando necesites invocar un puntos de conexión de agente. Para la instalación, consulte Implementación de un agente hospedado.

Comience con Microsoft Foundry Skill

Los agentes de codificación funcionan mejor cuando ya conocen las azd ai convenciones. La habilidad de Microsoft Foundry proporciona ese conocimiento a un agente de programación: genera comandos correctos azd ai y la integración de Foundry, y aplica las prácticas descritas en este artículo: establecer el contexto del proyecto, pasar --no-prompt y solicitar --output json para obtener resultados estructurados. Dirige primero tu agente de codificación hacia la skill y, a continuación, utiliza los patrones del resto de este artículo para revisar y reforzar lo que genera.

Establecer el contexto del proyecto una vez

Cada comando de recursos, como connection, toolbox, skill o routine, necesita un punto de conexión de proyecto de Foundry al que dirigirse. En la automatización, establezca ese punto de conexión una vez por sesión, trabajo de CI o invocación de agente de codificación y después úselo para el resto de la ejecución.

Hay dos patrones.

Fija una vez con azd ai project set

Cuando desee que el contexto se conserve entre shells sin exportar una variable de entorno, establézcalo en la configuración global:

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> es totalmente no interactivo cuando ya conoce la dirección URL. azd ai project show confirma qué fuente resolvió el extremo activo. Úsalo al inicio de una sesión si no estás seguro del estado en el que se encuentra el host.

Establecimiento de una variable de entorno

Establezca FOUNDRY_PROJECT_ENDPOINT en el entorno donde se ejecuta el script o el agente de codificación. Cada comando azd ai lo recoge automáticamente tras el entorno azd del proyecto y la configuración global.

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

Este patrón encaja bien con CI porque los secretos y la configuración suelen llegar ya como variables de entorno, y no hay ningún estado global que limpiar entre trabajos.

Para obtener una explicación completa de cómo resuelve la CLI el punto de conexión, incluido el orden de precedencia, consulte Establecimiento del contexto del proyecto azd.

Deshabilitar avisos

Cada azd ai comando acepta --no-prompt. Al establecerlo, el comando produce un error rápido en lugar de bloquear la entrada interactiva. La falta de un argumento obligatorio o de una confirmación delete que, de otro modo, esperaría una pulsación de tecla provoca un error inmediato cuando se utiliza la salida estructurada.

Configura siempre --no-prompt en CI y en las invocaciones del agente de código.

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

Obtención de la salida JSON

La mayoría de los comandos azd ai admiten --output json, incluidos los comandos de recursos connection, toolbox, skill y routine y azd ai agent show. Úsalo para analizar el resultado de forma fiable con jq, ConvertFrom-Json o el analizador JSON de tu lenguaje, en lugar de extraer la salida de texto legible para humanos. El comando azd ai agent invoke usa --output raw para la respuesta del servidor sin modificar.

# 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

La salida de texto es para humanos y puede cambiar entre versiones. La estructura JSON es el contrato estable.

Crea recursos de forma idempotente

create no es un upsert. Si el recurso con nombre ya existe, se producirá un error en la nueva ejecución. Este valor predeterminado funciona bien para los recursos compartidos con ámbito de proyecto, ya que impide que un autor de llamada sobrescriba silenciosamente el estado de otro autor de la llamada.

Para la automatización que debe realizarse correctamente independientemente del estado anterior, los connection comandos aceptan --force para reemplazar el recurso existente.

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 solo necesita cambiar algunos campos y desea conservar todo lo demás, use update. O bien, use los subcomandos de colección dedicados como tool, tag, metadatay key.

Creación de un cuadro de herramientas a partir de un archivo

Para una caja de herramientas de varias entradas que agrupa herramientas, conexiones y habilidades predefinidas, coloca la definición completa en un archivo YAML y pasa --from-file a azd ai toolbox create. El archivo usa la forma AgentSchema correspondiente.

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

--from-file es una entrada que se lee una sola vez en el momento de la invocación. La CLI no realiza un seguimiento ni vuelve a leer el archivo, por lo que las futuras modificaciones en YAML no tienen ningún efecto hasta que vuelva a ejecutar el comando. Cree conexiones con marcas explícitas (--kind, --target, --auth-typey las marcas de credenciales coincidentes) y, a continuación, haga referencia a ellas por su nombre desde el archivo del cuadro de herramientas.

Invocar un agente desplegado sin un proyecto azd

Cuando un agente de codificación o un script necesita llamar a un agente implementado que reside fuera de su directorio de trabajo, use --agent-endpoint para dirigirse a él directamente. Este enfoque omite tanto azure.yaml como azd env activo. La dirección URL solo es suficiente.

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

Utilice esta configuración cuando la CI de un repositorio necesite llamar a un agente perteneciente a otro repositorio, o cuando un servidor MCP actúe como interfaz para varios agentes y solo conozca las URL de sus endpoints. Para obtener el conjunto completo de opciones de invoke, consulte Invocar a un agente hospedado.

Pasar secretos a una ejecución local

Para iniciar el agente localmente con secretos, configúrelos como azd variables de entorno y haga referencia a ellos desde el env mapa de su azure.ai.agent servicio en azure.yaml. Los valores residen en .azure/<env>/.env, que está ignorado por git de forma predeterminada.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

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

Para los secretos que no deberían almacenarse en un archivo local .env, guárdelos en una conexión de proyecto de Foundry y haga referencia a ellos mediante un marcador de posición ${{connections.<name>.credentials.<field>}}. Consulte Ejecutar un agente hospedado localmente para obtener la superficie de ejecución local completa.

Crear una configuración breve

Este script de Bash combina los patrones anteriores. Fija el contexto del proyecto, crea una conexión y una caja de herramientas de forma idempotente, vincula una herramienta a la caja de herramientas y verifica el resultado analizando 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 garantiza que el script genere un error rápidamente si se produce un error en cualquier paso. En combinación con --no-prompt, esto te proporciona un código de salida determinista adecuado para las puertas de control de la integración continua (CI).

Revisar la resolución del puntos de conexión

Los agentes de programación pueden predecir a qué proyecto de Foundry se dirigirá un comando siguiendo este orden de prioridad. El primer origen que produce un valor gana; no se consultan fuentes posteriores.

1. Indicador --project-endpoint (o -p) (siempre prevalece).
2. Dentro de un proyecto azd: el valor activo de azd env.
3. Configuración global (establecida por azd ai project set).
4. La variable de entorno FOUNDRY_PROJECT_ENDPOINT.
5. Error con una sugerencia estructurada para ejecutar azd ai project set o pasar --project-endpoint.

Para obtener la explicación completa, incluida la forma en que el contexto independiente interactúa con el trabajo en el proyecto, consulte Establecimiento del contexto del proyecto azd.

Aplicar consejos del agente de codificación

• Pase siempre --no-prompt y añada --output json a los comandos que lo admitan. Juntos, proporcionan un código de salida predecible más un resultado analizable.
• Compruebe el contexto resuelto con azd ai project show al principio de una sesión si no está seguro de en qué estado está el host. Es una llamada sencilla y de solo lectura.
• Si se produce un fallo, es preferible analizar la sugerencia estructurada en la salida de error antes de decidir los siguientes pasos. Por ejemplo, un error "No Foundry project endpoint resolved" implica que debe ejecutar azd ai project set, o establecer FOUNDRY_PROJECT_ENDPOINT, antes de reintentar.
• Use --debug solo al diagnosticar un problema. Genera una salida detallada de varias líneas que resulta difícil de analizar y que nunca se concibió como una interfaz programática.
• Considere recuperables los fallos de create que indican "ya existe". Vuelva a ejecutar con --force si el recurso es suyo y quiere reemplazarlo, o use update y los subcomandos de la colección si solo necesita cambiar una parte.

Contenido relacionado

• Establezca el contexto del proyecto azd para comprender cómo resuelve la CLI el punto de conexión del proyecto Foundry.
• Configura CI/CD para agentes hospedados con la CLI de Azure Developer para patrones que ejecutan azd ai en pipelines.
• Invoque un agente hospedado para obtener opciones completas azd ai agent invoke , incluido --agent-endpoint.