Use o azd ai com agentes de programação e scripts

Use azd ai dos agentes de código e scripts com o mesmo comportamento que humanos têm em um terminal. Você define um contexto independente, desativa prompts, processa a saída JSON e invoca pontos de extremidade diretos do agente para uma automação confiável.

Pré-requisitos

• As extensões do Azd Foundry instaladas.
• Uma azd sessão autenticada.
• Um endpoint do projeto do Microsoft Foundry para os comandos que você deseja executar. Para obter mais informações, consulte Definir o contexto do projeto azd.
• Opcional: um agente hospedado implantado quando você precisar invocar um endpoint de um agente. Para configurar, consulte Implantar um agente hospedado.

Introdução ao Microsoft Foundry Skill

Os agentes de codificação funcionam melhor quando já conhecem as azd ai convenções. O Microsoft Foundry Skill fornece a um agente de codificação esse conhecimento: ele gera comandos corretos azd ai e a fiação do Foundry e aplica as práticas neste artigo -- definindo o contexto do projeto, passando --no-prompte solicitando --output json resultados estruturados. Direcione primeiro seu agente de programação para a habilidade e, em seguida, use os padrões no restante deste artigo para revisar e fortalecer o que ele produz.

Definir o contexto do projeto uma vez

Cada comando de recurso, como connection, toolbox, skill ou routine, precisa de um endpoint do projeto no Foundry como destino. Na automação, defina esse endpoint uma vez por sessão, job de CI ou invocação do agente de código e depois use-o durante o restante da execução.

Há dois padrões.

Fixe uma vez com azd ai project set

Quando você quiser que o contexto persista entre shells sem exportar uma variável de ambiente, defina-o na configuração 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> é totalmente não interativo quando você já conhece a URL. azd ai project show confirma qual fonte determinou o ponto de extremidade ativo. Use-o na parte superior de uma sessão se você não tiver certeza de em que estado o host está.

Definir uma variável de ambiente

Defina FOUNDRY_PROJECT_ENDPOINT no ambiente em que seu script ou agente de codificação é executado. Cada comando azd ai o reconhece automaticamente após considerar o ambiente do azd no projeto e a configuração global.

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

Esse padrão se ajusta bem à CI porque os segredos e a configuração geralmente já chegam como variáveis de ambiente e não há estado global para limpar entre trabalhos.

Para obter uma explicação detalhada de como a CLI resolve o endpoint, incluindo a ordem de precedência, consulte Definir o contexto do projeto do azd.

Desativar avisos

Cada azd ai comando aceita --no-prompt. Quando você o define, o comando falha rapidamente em vez de bloquear a entrada interativa. A ausência de um argumento obrigatório ou uma confirmação delete que, de outra forma, aguardaria o pressionamento de uma tecla, passa a ser um erro imediato com saída estruturada.

Sempre defina --no-prompt na CI e nas invocações do agente de codificação.

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

Obter saída JSON

A maioria dos comandos azd ai oferece suporte a --output json, incluindo os comandos de recurso connection, toolbox, skill e routine, e azd ai agent show. Use isso para processar o resultado de modo confiável com jq, ConvertFrom-Json ou o analisador JSON da sua linguagem, em vez de extrair dados da saída de texto legível por humanos. O comando azd ai agent invoke usa --output raw para a resposta não modificada do servidor.

# 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

A saída de texto é para humanos e pode mudar entre versões. A forma JSON é o contrato estável.

Criar recursos de forma idempotente

create não é um upsert. Se o recurso nomeado já existir, uma nova execução falhará. Essa configuração padrão funciona bem para recursos compartilhados no escopo do projeto porque impede que um chamador sobrescreva silenciosamente o estado de outro chamador.

Para automações que devem ser bem-sucedidas independentemente do estado anterior, os comandos connection aceitam --force para substituir o 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

Se você precisar apenas alterar alguns campos e quiser preservar todo o resto, use update. Ou use os subcomandos de coleção dedicados, como tool, tage metadatakey.

Criar uma caixa de ferramentas a partir de um arquivo

Para uma caixa de ferramentas com várias entradas que reúne ferramentas integradas, conexões e recursos, coloque a definição completa em um arquivo YAML e passe --from-file para o azd ai toolbox create. O arquivo usa a forma AgentSchema correspondente.

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

--from-file é uma entrada lida uma única vez no momento da invocação. A CLI não rastreia nem relê o arquivo, portanto, as edições futuras no YAML não têm efeito até que você execute novamente o comando. Crie conexões com sinalizadores explícitos (--kind, --targete --auth-typeos sinalizadores de credencial correspondentes) e, em seguida, faça referência a eles pelo nome do arquivo da caixa de ferramentas.

Invocar um agente implantado sem um projeto do azd

Quando um agente de codificação ou script precisar chamar um agente implantado que está fora de seu diretório de trabalho, use --agent-endpoint para direcioná-lo diretamente. Essa abordagem contorna tanto azure.yaml quanto o azd env ativo. Só a URL é 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

Use essa configuração quando o CI de um repositório precisar chamar um agente de outro repositório ou quando um servidor MCP atuar como interface para vários agentes e conhecer apenas as URLs de seus pontos de extremidade. Para obter o conjunto completo de invoke opções, consulte Invocar um agente hospedado.

Passe segredos para uma execução local

Para iniciar o agente localmente com segredos, defina-os como variáveis ​​de ambiente azd e faça referência a eles no mapa env do seu serviço azure.ai.agent em azure.yaml. Os valores ficam em .azure/<env>/.env, que é ignorado pelo Git por padrão.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

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

Para segredos que não devem ficar em um arquivo local .env, armazene-os em uma conexão de um projeto do Foundry e faça referência a eles usando um marcador ${{connections.<name>.credentials.<field>}}. Consulte Executar um agente hospedado localmente para a superfície de execução local completa.

Criar um script de configuração rápida

Esse script bash combina os padrões acima. Ele define o contexto do projeto, cria uma conexão e um kit de ferramentas de modo idempotente, conecta uma ferramenta ao kit de ferramentas e verifica o resultado analisando o 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 garante que o script falhe rapidamente se alguma etapa apresentar erro. Em conjunto com --no-prompt, isso fornece um código de saída determinístico adequado para as validações de CI.

Examinar a resolução do ponto de extremidade

Os agentes de programação podem prever a qual projeto do Foundry um comando será direcionado percorrendo esta ordem de prioridade. A primeira fonte que produz um valor ganha; fontes posteriores não são consultadas.

1. Sinalizador --project-endpoint (ou -p) (sempre vence).
2. Dentro de um projeto azd: o valor ativo do azd env.
3. Configuração global (definida por azd ai project set).
4. A variável de ambiente FOUNDRY_PROJECT_ENDPOINT.
5. Erro com uma sugestão estruturada para executar azd ai project set ou passar --project-endpoint.

Para obter a explicação completa, incluindo como o contexto autônomo interage com o trabalho no projeto, consulte Definir o contexto do projeto azd.

Aplicar dicas de agente de codificação

• Sempre passe --no-prompt e adicione --output json aos comandos que o suportam. Juntos, eles oferecem um código de saída previsível mais um resultado analisável.
• Verifique, no início de uma sessão, o contexto determinado com azd ai project show, se você não tiver certeza de qual é o estado do host. É uma chamada de baixo custo somente leitura.
• Em caso de falha, prefira analisar a sugestão estruturada na saída de erro em vez de decidir as próximas etapas. Por exemplo, um erro "Nenhum ponto de extremidade de projeto do Foundry foi resolvido" indica que você deve executar azd ai project set ou definir FOUNDRY_PROJECT_ENDPOINT antes de tentar novamente.
• Use --debug somente ao diagnosticar um problema. Ele produz uma saída verbosa, em várias linhas, que é difícil de analisar e nunca foi concebida como uma interface programática.
• Trate erros com "já existe" em create como recuperáveis. Execute novamente com --force se você pretende substituir o recurso inteiro, ou mude para update e os subcomandos da coleção se você só precisar alterar parte dele.

Conteúdo relacionado

• Defina o contexto do projeto do azd para entender como a CLI resolve o ponto de extremidade do projeto Foundry.
• Configure o CI/CD para agentes hospedados com a CLI do Azure Developer para padrões executados em pipelines azd ai.
• Invoque um agente hospedado para obter opções completas azd ai agent invoke , incluindo --agent-endpoint.