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

Utiliza azd ai a partir de agentes de programação e scripts com o mesmo comportamento que os humanos têm quando utilizam um terminal. Definis um contexto autónomo, desativas os pedidos, processas a saída JSON e invocas endpoints diretos de agente para automatização fiável.

Pré-requisitos

• As extensões do azd Foundry estão instaladas.
• Uma sessão azd autenticada.
• Um endpoint de projeto Microsoft Foundry para os comandos que quer executar. Para mais informações, consulte Definir o contexto do projeto azd.
• Opcional: um agente alojado e implementado quando for necessário invocar um endpoint do agente. Para configuração, veja Implementar um agente hospedado.

Comece com a Microsoft Foundry Skill

Os agentes de programação funcionam melhor quando já conhecem as azd ai convenções. O Microsoft Foundry Skill fornece esse conhecimento a um agente de programação: gera comandos corretos azd ai e a configuração do Foundry, e aplica as práticas deste artigo — definindo o contexto do projeto, passando --no-prompt e pedindo --output json para obter resultados estruturados. Direciona primeiro o teu agente de programação para a competência e depois usa os padrões do resto deste artigo para rever e robustecer os resultados que ele produz.

Definir o contexto do projeto uma vez

Cada comando de recurso, como connection, toolbox, skill, ou routine, precisa de um endpoint de projeto Foundry para ser alvo. Na automação, define esse endpoint uma vez por sessão, job CI ou invocação de agente de código, e depois usa-o para o resto da execução.

Existem dois padrões.

Fixa uma vez com azd ai project set

Quando quiser que o contexto persista entre shells sem exportar uma variável de ambiente, defina-o em 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 já conhece a URL. azd ai project show confirma qual a fonte que resolveu o endpoint ativo. Usa-o no início de uma sessão se não tiveres a certeza em que estado está o anfitrião.

Definir uma variável de ambiente

Defina FOUNDRY_PROJECT_ENDPOINT no ambiente onde o seu script ou agente de código é executado. Todos os azd ai comandos captam-no automaticamente depois do ambiente azd dentro do projeto e da configuração global.

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

Este padrão encaixa-se bem no CI porque os segredos e a configuração normalmente já chegam como variáveis de ambiente, e não há um estado global para limpar entre tarefas.

Para a explicação completa de como a CLI resolve o endpoint, incluindo a ordem de precedência, veja Definir o contexto do projeto azd.

Desativar prompts

Todos os azd ai comandos aceitam --no-prompt. Quando a defines, o comando falha de imediato em vez de ficar bloqueado à espera de entrada interativa. Um argumento obrigatório em falta ou uma delete confirmação que, de outra forma, esperaria por uma pressão de tecla torna-se um erro imediato com saída estruturada.

Defina sempre --no-prompt na CI e nas invocações do 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

Obter saída JSON

A maioria dos comandos azd ai suporta --output json, incluindo os comandos de recurso connection, toolbox, skill e routine, e azd ai agent show. Use-o para analisar o resultado de forma fiável com jq, ConvertFrom-Json, ou com o parser JSON da sua linguagem em vez de raspar a 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

O resultado de texto destina-se a humanos e pode mudar entre versões. A forma JSON é o contrato estável.

Criar recursos de modo idempotente

create não é um upsert. Se o recurso nomeado já existir, uma nova execução falha. Esta predefinição funciona bem para recursos partilhados no âmbito do projeto, porque impede que um autor da chamada sobrescreva silenciosamente o estado de outro.

Para automatizações que têm de ser bem-sucedidas independentemente do estado prévio, 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 só precisares de mudar alguns campos e quiseres preservar todo o resto, usa update. Ou então usa os subcomandos dedicados à coleção como tool, tag, metadata, e key.

Crie uma caixa de ferramentas a partir de um ficheiro

Para uma caixa de ferramentas com várias entradas que inclui ferramentas, ligações e competências integradas, coloque a definição completa num ficheiro YAML e passe --from-file a azd ai toolbox create. O ficheiro utiliza a estrutura AgentSchema correspondente.

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

--from-file é uma entrada de utilização única lida no momento da invocação. A CLI não rastreia nem relê o ficheiro, por isso futuras edições no YAML não têm efeito até voltares a executar o comando. Crie ligações com sinalizadores explícitos (--kind, --target, --auth-type e os sinalizadores de credenciais correspondentes) e, em seguida, refira-se a elas pelo nome no ficheiro da caixa de ferramentas.

Invocar um agente implementado sem um projeto do azd

Quando um agente de codificação ou script precisa de chamar um agente implementado que vive fora do seu diretório de trabalho, use --agent-endpoint para o direcionar diretamente. Esta abordagem ignora tanto azure.yaml como o ambiente azd ativo. Só o URL já chega.

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 esta forma quando o CI de um repositório precisar de chamar um agente pertencente a um repositório diferente, ou quando um servidor MCP apresenta vários agentes e só conhece as URLs dos seus endpoints. Para o conjunto completo de invoke opções, veja Invocar um agente hospedado.

Passe segredos para uma corrida local

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

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 num ficheiro local .env, guarde-os numa ligação de projeto do Foundry e referencie-os com um marcador de posição ${{connections.<name>.credentials.<field>}}. Veja Executar um agente hospedado localmente para a superfície completa de execução local.

Criar uma breve configuração

Este script bash combina os padrões acima. Fixa o contexto do projeto, cria uma ligação e uma caixa de ferramentas de forma idempotente, liga uma ferramenta à caixa de ferramentas e verifica o resultado através da análise 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 falha rapidamente se algum passo falhar. Combinado com --no-prompt, isso dá-lhe um código de saída determinístico adequado para portas CI.

Rever a resolução dos endpoints

Os agentes de programação podem prever qual o projeto Foundry que um comando terá como alvo, seguindo esta ordem de prioridade. A primeira fonte que produz um valor vence; Fontes posteriores não são consultadas.

1. --project-endpoint (ou -p) Flag (ganha sempre).
2. Num projeto azd: o valor ativo de azd env.
3. Configuração global (definida por azd ai project set).
4. FOUNDRY_PROJECT_ENDPOINT variável de ambiente.
5. Erro com uma sugestão estruturada para executar azd ai project set ou fornecer --project-endpoint.

Para a explicação completa, incluindo como o contexto autónomo interage com o trabalho dentro do projeto, veja Definir o contexto do projeto azd.

Aplicar sugestões do agente de programação

• Passa sempre --no-prompt, e adiciona --output json aos comandos que o suportam. Juntos, dão-te um código de saída previsível mais um resultado analisável.
• Verifica o contexto determinado com azd ai project show no início de uma sessão, se não tiveres a certeza do estado do anfitrião. É uma chamada barata, só de leitura.
• Em caso de falha, prefira interpretar a sugestão estruturada na saída de erro em vez de decidir os passos seguintes. Por exemplo, um erro "Nenhum endpoint do projeto Foundry foi resolvido" indica que deve executar azd ai project set ou definir FOUNDRY_PROJECT_ENDPOINT antes de voltar a tentar.
• --debug Use apenas ao diagnosticar um problema. Produz uma saída extensa, em várias linhas, que é difícil de analisar e nunca foi pensada para ser uma interface programática.
• Trate as falhas create com "já existe" como recuperáveis. Executa novamente com --force se o recurso for teu para o substituir, ou muda para update e para os subcomandos da coleção caso só precises de alterar parte dele.

Conteúdo relacionado

• Defina o contexto do projeto azd para perceber como a CLI resolve o endpoint do projeto Foundry.
• Configurar CI/CD para agentes alojados com a CLI do Azure Developer para padrões que são executados azd ai em pipelines.
• Invocar um agente hospedado para opções completas azd ai agent invoke , incluindo --agent-endpoint.