Desenvolvimento de agente com a CLI do Desenvolvedor do Azure

A CLI do Desenvolvedor do Azure (azd) e sua azd ai agent extensão fornecem um único fluxo de trabalho de linha de comando para passar da ideia para um agente hospedado pronto para produção no Microsoft Foundry. Este artigo explica o percurso do desenvolvedor, os arquivos que definem um agente e os principais conceitos que você encontra ao longo do caminho.

Este artigo é para desenvolvedores que preferem um fluxo de trabalho centrado no terminal e automatizável por scripts, em vez do portal do Foundry ou de SDKs de linguagem.

O percurso do desenvolvedor

O azd ai fluxo de trabalho segue o mesmo ciclo de vida se você criar um pequeno protótipo ou um agente de produção. Você cria a estrutura inicial de um projeto uma vez e, depois, combina e alterna comandos conforme o projeto evolui.

Tipos de agente

A azd ai agent extensão tem como foco agentes hospedados.

Os agentes hospedados oferecem controle total sobre o runtime, a estrutura e as integrações de ferramentas, enquanto o Foundry lida com a infraestrutura, o dimensionamento e o gerenciamento de sessão.

Arquivos de configuração

Três arquivos definem como um agente é criado e implantado.

A principal diferença é que agent.yaml descreve o que seu agente é, enquanto azure.yaml descreve como ele é implantado.

Os recursos que residem no próprio projeto foundry, como conexões, caixas de ferramentas, habilidades e rotinas, são gerenciados por meio de comandos diretos azd ai em vez de declarados em agent.yaml.

Substituição de variável

Você verá duas sintaxes variáveis nos arquivos de projeto do agente:

• ${VAR_NAME} é um azd marcador para uma variável de ambiente. Isso é resolvido a partir de .azure/<env>/.env no momento da implantação, assim o mesmo agent.yaml funciona em ambientes como desenvolvimento, homologação e produção.
• {{ parameter }} é um parâmetro do modelo de manifesto. Ele é resolvido durante azd ai agent init quando um modelo é estruturado em um projeto concreto.

Onde a CLI é executada

Os azd ai comandos funcionam dentro e fora de um azd diretório de projeto:

• Dentro de um projeto azd, os comandos determinam o endpoint do projeto Foundry a partir do ambiente azd ativo.
• Fora de um projeto azd, defina o contexto ativo uma vez com azd ai project set <endpoint> ou passe --project-endpoint em um comando de recurso individual (connection, toolbox, skill ou routine). Como alternativa, azd ai lê a variável de ambiente FOUNDRY_PROJECT_ENDPOINT.
• Um ambiente no projeto sempre tem precedência sobre o contexto global, portanto, a alteração de diretórios em um projeto redireciona a CLI no ponto de extremidade desse projeto.

Protocols

Um protocolo define o contrato HTTP entre o Foundry e o contêiner do agente. Seu agente escuta na porta 8088 e responde a uma sonda de integridade, independentemente do protocolo usado.

Para obter a especificação completa, consulte o contrato de runtime do agente hospedado.

Sessões e conversas

As sessões são identificadas por um session_id. Quando você executa azd ai agent invoke, o Foundry reutiliza a sessão da última invocação por padrão. Use --new-session para iniciar novamente ou --session-id <id> para direcionar uma sessão específica.

Recursos em um projeto do Foundry

Um projeto do Foundry hospeda mais do que agentes. Também contém recursos compartilhados aos quais os agentes recorrem em tempo de execução. A CLI gerencia cada um por meio de um grupo de comandos dedicado.

Esses recursos são compartilhados entre desenvolvedores e agentes no mesmo projeto. Cada grupo de comandos expõe os verbos padrão create, update, delete, show e list.

Avaliar e melhorar um agente

Depois que um agente é executado, dois fluxos de trabalho relacionados ajudam você a medir e melhorar sua qualidade:

• A avaliação executa seu agente com um conjunto de dados, atribui pontuações às respostas com um ou mais avaliadores e fornece um indicador agregado de qualidade. Você o gerencia com azd ai agent eval.
• A otimização reescreve iterativamente o prompt do agente para levantar um sinal de avaliação. Ele usa uma avaliação como sua função objetiva e produz um prompt de candidato que você revisa e aceita. Você gerencia isso com azd ai agent optimize.

Para obter detalhes, consulte Executar avaliações do agente com a CLI do azd e Otimizar prompts do agente.

Ciclo de vida da implantação

O loop de desenvolvedor completo se condensa em uma breve sequência de comandos. Crie a estrutura inicial uma vez e depois use os comandos diretos conforme seu projeto evolui.

# Scaffold a project from a template or your existing code
azd ai agent init

# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"

# Provision infrastructure and deploy the agent
azd up

# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent

# Evaluate quality
azd ai agent eval generate
azd ai agent eval run

# Tear down all Azure resources
azd down

Conteúdo relacionado

• Início Rápido: Implantar seu primeiro agente hospedado
• O que são agentes hospedados?
• Contrato de runtime do agente hospedado
• Ciclo de vida de desenvolvimento do agente