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 pronto para produção no Microsoft Foundry. Você pode desenvolver agentes hospedados baseados em código e agentes de voz declarativos baseados em prompt. 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 dá suporte a tipos de agente declarativos e baseados em código.

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.

Os agentes de voz baseados em prompt não exigem um contêiner personalizado. Se você precisar executar um pipeline de áudio personalizado de fala para fala ou em cascata em seu próprio contêiner, crie um agente de voz com um agente hospedado e use o protocolo invocations_ws.

Para manter a lógica de conversa em um agente de texto hospedado enquanto o Voice Live manipula áudio, use o fluxo de trabalho do wrapper de voz hospedado. O wrapper e o destino são serviços separados no mesmo azure.yaml projeto. Esse fluxo não substitui o fluxo de pipeline de áudio personalizado invocations_ws existente.

Antes de usar as opções da CLI de voz de visualização pública, verifique sua 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 usa um azure.yaml arquivo na raiz do projeto para declarar o agente e seu modelo de provisionamento e implantação. O arquivo usa um modelo de serviço dividido, em que cada serviço nomeado tem um host valor como azure.ai.project, , azure.ai.agent, azure.ai.connection, azure.ai.toolbox, azure.ai.skillou azure.ai.routine.

O serviço azure.ai.agent define seu agente hospedado em linha e usa uses: para referenciar outros serviços, como o projeto, conexões, caixas de ferramentas, habilidades e rotinas. Não há nenhum arquivo autônomo agent.yaml ou agent.manifest.yaml no modelo de projeto atual do hosted-agent azd.

Para um agente de voz baseado em prompt, azure.yaml armazena a definição do agente declarativo, incluindo kind: prompt-voice, o modelo, o tipo de modelo e o nome do agente. Ele não inclui um runtime de contêiner de agente hospedado. Para personalizar instruções, áudio, detecçã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 faz referência ao nome de serviço do destino hospedado. A dependência do wrapper uses determina a implantação, e conversationEngine.version usa por padrão a versão implantada pelo ambiente atual. Consulte a referência do serviço de voz para os campos de configuração.

Substituição de variável

Use ${VAR_NAME} em azure.yaml para valores que diferem de acordo com o ambiente azd. O espaço reservado é resolvido a partir de .azure/<env>/.env no momento da implantação ou execução, portanto, o mesmo azure.yaml funciona em ambientes como desenvolvimento, teste e produção.

Onde a CLI é executada

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

• Em um projeto azd, os comandos determinam o ponto de extremidade do projeto Foundry com base no 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 investigação de integridade, independentemente do protocolo usado.

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

Essas configurações de protocolo se aplicam a contêineres de agente hospedado. Os agentes de voz com base em prompts não configuram um protocolo de agente hospedado.

azd ai agent invoke não oferece suporte a conversas por voz para agentes de voz baseados em prompts ou wrappers de voz hospedados. Para obter as diretrizes de comportamento e teste da CLI, consulte as limitações do agente de voz.

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 relação a um conjunto de dados, pontua as 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 de modo iterativo o prompt do agente para remover 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ê o gerencia 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.

Para o fluxo gerenciado de agente de voz, consulte 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: Criar um agente de voz com prompts
• Configurar um agente de voz
• 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