Desenvolvimento de agentes com o Azure Developer CLI

O Azure Developer CLI (azd) e a sua azd ai agent extensão dão-te um único fluxo de trabalho na linha de comandos para passar da ideia a um agente pronto para produção no Microsoft Foundry. Pode desenvolver agentes hospedados baseados em código e agentes de voz declarativos baseados em prompts. 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 azd ai agent extensão suporta tipos de agentes baseados em código e declarativos.

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.

Agentes de voz baseados em prompts não requerem um contentor personalizado. Se precisares de executar um pipeline personalizado de fala para fala ou um pipeline de áudio em cascata no teu próprio contentor, constrói um agente de voz com um agente hospedado e usa o protocolo invocations_ws.

Para manter a lógica da conversa num agente de texto alojado enquanto o Voice Live gere o áudio, use o fluxo de trabalho de encapsulamento de voz alojado. O wrapper e o target são serviços separados no mesmo azure.yaml projeto. Este fluxo não substitui o fluxo personalizado do pipeline de áudio invocations_ws existente.

Antes de usar as opções de pré-visualização pública da CLI de voz, verifique a extensão instalada conforme descrito nos pré-requisitos de início rápido do agente de voz.

Arquivos de configuração

Um projeto de agente hospedado utiliza um azure.yaml ficheiro na raiz do projeto para declarar tanto o agente como o seu modelo de provisionamento e implementação. O ficheiro utiliza um modelo de serviço dividido, onde cada serviço nomeado tem um host valor como azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox, azure.ai.skill, ou azure.ai.routine.

O serviço azure.ai.agent define o seu agente alojado na linha e utiliza uses: para referenciar outros serviços, como o projeto, ligações, caixas de ferramentas, competências e rotinas. Não existe um ficheiro agent.yaml ou agent.manifest.yaml autónomo no modelo atual do projeto hosted-agent azd.

Para um agente de voz baseado em prompts, azure.yaml armazena a definição declarativa do agente, incluindo kind: prompt-voice, o modelo, o tipo de modelo e o nome do agente. Não inclui um ambiente de execução de contentores de agente alojado. Para personalizar instruções, áudio, deteção de turnos, transcrição, saída de voz, ferramentas e saudações, consulte Configurar um agente de voz.

Para um wrapper de voz hospedado, conversationEngine.name refere-se ao nome do serviço do alvo hospedado. A dependência do invólucro uses determina a ordem da implementação, e conversationEngine.version utiliza por predefinição a versão implementada pelo ambiente atual. Consulte a referência do serviço de voz para os campos de configuração.

Substituição de variáveis

Utilize ${VAR_NAME} em azure.yaml para valores que diferem consoante o ambiente azd. O marcador de posição é resolvido a partir de .azure/<env>/.env no momento da implementação ou da execução, por isso, o mesmo azure.yaml funciona em ambientes como desenvolvimento, pré-produção e produção.

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.

Estas definições de protocolo aplicam-se a contentores de agente hospedado. Os agentes de voz baseados em instruções não configuram um protocolo de agente alojado.

azd ai agent invoke não suporta conversas de voz para agentes de voz baseados em prompts nem wrappers de voz hospedados. Para o comportamento da CLI e orientações de testes, consulte Limitações do agente de voz.

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.

Para o percurso gerido do agente de voz, veja Início rápido: Criar um agente de voz com prompt.

# 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: Crie um agente de voz com prompt
• Configurar um agente de voz
• 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