Desenvolvimento de agentes com o Azure Developer CLI

A CLI do Azure Developer (azd) e a sua azd ai agent extensão dão-lhe um único fluxo de trabalho na linha de comandos para passar da ideia a um agente hospedado pronto para produção no Microsoft Foundry. Este artigo explica a jornada do programador, os ficheiros que definem um agente e os conceitos centrais que encontra pelo caminho.

Este artigo destina-se a programadores que preferem um fluxo de trabalho scriptável centrado no terminal em vez do portal Foundry ou dos SDKs de linguagem.

A jornada do programador

O azd ai fluxo de trabalho segue o mesmo ciclo de vida, quer constróis um pequeno protótipo ou um agente de produção. Cria-se a estrutura base de um projeto uma vez e, depois, combinam-se os comandos conforme necessário, à medida que o projeto evolui.

Tipos de agentes

A extensão azd ai agent centra-se em agentes alojados.

Os agentes alojados dão-lhe controlo total sobre o runtime, framework e integrações com ferramentas, enquanto o Foundry trata da infraestrutura, escalabilidade e gestão de sessões.

Arquivos de configuração

Três ficheiros definem como um agente é construído e implementado.

A distinção chave é que agent.yaml descreve o que é o seu agente, enquanto azure.yaml descreve como é implementado.

Os recursos que vivem no próprio projeto Foundry, como ligações, caixas de ferramentas, competências e rotinas, são geridos através de comandos diretos azd ai em vez de declarados em agent.yaml.

Substituição de variáveis

Vês duas sintaxes variáveis nos ficheiros do projeto agente:

• ${VAR_NAME} é uma azd variável de ambiente provisória. É resolvido a partir de .azure/<env>/.env no momento da implementação, pelo que o mesmo agent.yaml funciona em ambientes como desenvolvimento, staging e produção.
• {{ parameter }} é um parâmetro do modelo de manifesto. É resolvido durante azd ai agent init quando um modelo é gerado para um projeto concreto.

Onde corre o CLI

Os azd ai comandos funcionam tanto dentro como 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 num comando de recurso individual (connection, toolbox, skill ou routine). Como alternativa, azd ai lê a variável de ambiente FOUNDRY_PROJECT_ENDPOINT.
• Um ambiente dentro do projeto tem sempre prioridade sobre o contexto global, por isso mudar diretórios para um projeto redireciona a CLI no ponto final desse projeto.

Protocols

Um protocolo define o contrato HTTP entre o Foundry e o seu contentor de agente. O teu agente ouve na porta 8088 e serve como sonda de saúde, independentemente do protocolo.

Para a especificação completa, veja Contrato de runtime do agente hospedado.

Sessões e conversas

As sessões são identificadas por um session_id. Quando executas azd ai agent invoke, o Foundry reutiliza a sessão da tua última invocação por defeito. Use --new-session para começar do zero ou --session-id <id> para focar numa sessão específica.

Recursos sobre um projeto de fundição

Um projeto Foundry inclui mais do que apenas agentes. Também mantém recursos partilhados que os agentes consultam em tempo de execução. A CLI gere cada um através de um grupo de comando dedicado.

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

Avalie e melhore um agente

Depois de um agente ser executado, dois fluxos de trabalho relacionados ajudam-no a medir e melhorar a sua qualidade:

• A avaliação compara o seu agente com um conjunto de dados, avalia as respostas com um ou mais avaliadores e reporta um sinal agregado de qualidade. Gere-o com azd ai agent eval.
• A otimização reescreve iterativamente o prompt do seu agente para melhorar um sinal de avaliação. Utiliza uma avaliação como função objetiva e produz um enunciado candidato que você revê e aceita. Gere-o com azd ai agent optimize.

Para mais detalhes, consulte Executar avaliações de agentes com a CLI azd e Otimizar os prompts de agentes.

Ciclo de vida de implementação

O ciclo completo de desenvolvimento condensa-se numa sequência curta de comandos. Cria a estrutura uma vez e depois utiliza os comandos diretos à medida que o teu projeto cresce.

# 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: Implemente o seu primeiro agente alojado
• O que são agentes hospedados?
• Contrato de execução de agente hospedado
• Ciclo de vida do desenvolvimento do agente