Desenvolvimento de agentes com o Azure Developer CLI

Importante

Os itens marcados como pré-visualização neste artigo estão atualmente em pré-visualização. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e a Microsoft não a recomenda para cargas de trabalho de produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos Suplementares de Utilização para Microsoft Azure Previews.

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.

Stage O que fazes Onde aprender mais
Install Instale azd e as extensões do Foundry. Configura o teu ambiente de desenvolvimento
Andaime Inicialize um agente hospedado a partir de um template ou do seu código existente, ou crie um agente de voz baseado em prompts. Início rápido: Implementar um agente alojado ou Início rápido: Criar um agente de voz com prompt
Definir Configure o agente, modele dependências de implementação, protocolos, ferramentas e ambiente em azure.yaml. Crie o azure.yaml para agentes hospedados
Develop Escreve lógica para agentes, adiciona ferramentas usando uma caixa de ferramentas e testa localmente. Visão geral da caixa de ferramentas
Deploy Aprovisionar infraestrutura e implementar na Foundry. Implementar um agente alojado
Operar Monitorizar registos, gerir versões e automatizar execuções. Gerir agentes alojados
Evaluate Meça a qualidade do agente e melhore o prompt. Executa avaliações de agentes com o CLI azd

Tipos de agentes

A azd ai agent extensão suporta agentes alojados, de prompt e de voz.

Tipo Description Quando utilizar
Agente hospedado Uma aplicação que disponibilizas como código-fonte ou imagem de contentor. Precisas de lógica personalizada, integração com frameworks ou controlo total sobre o comportamento.
Agente de prompt Um agente definido inteiramente através de instruções e configurações de ferramentas, sem código personalizado. Queres um agente rápido, orientado por configuração, sem escrever código de aplicação.
Agente de voz Um agente de voz de prompt declarativo, ou um wrapper de voz que se liga a um agente hospedado. Precisa de uma experiência de voz em tempo real através de um cliente Voice Live.

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.

File Purpose Quem a mantém
azure.yaml Declara o projeto Foundry, implementações de modelos, serviço de agente alojado, dependências, protocolos, ferramentas, variáveis de ambiente, recursos de contentores e definições de implementação. Identidade do agente, modelo, protocolos, ferramentas e valores do ambiente estão presentes no azure.ai.agent serviço. A inicialização gera-o. Personaliza conforme necessário.

O azure.ai.agent serviço define o seu agente em linha ou através de uma raiz $ref explícita para uma definição direta em YAML ou JSON. Use azd ai agent add <service> --file <path> para um serviço com suporte a ficheiros. Os wrappers parametrizados AgentManifest não são suportados pela inicialização atual. A lista do serviço uses: faz referência a dependências como o projeto, ligações e caixas de ferramentas.

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 endpoint não vazio resolvido a partir do ambiente ativo tem precedência sobre o contexto global. Para o mecanismo de fallback da shell e o comportamento específico de comandos, veja Definir o contexto do 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.

Protocolo Estilo de API Quando utilizar
responses API de Respostas OpenAI (POST /responses) A escolha padrão, compatível com o ecossistema da API OpenAI.
invocations Contrato JSON personalizado (POST /invocations) Quando precisa do controlo total sobre o conteúdo dos pedidos e das respostas.

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

Conceito Description
Session Um ambiente de execução isolado para uma interação com um único agente. Cada sessão decorre no seu próprio sandbox com recursos dedicados.
Conversação Histórico de mensagens para o protocolo Responses. As invocações não persistem automaticamente o histórico de conversas.

As sessões são identificadas por um session_id. A CLI guarda a seleção de sessão por agente e reutiliza-a por defeito. Use --new-session para começar do zero ou --session-id <id> para focar numa sessão específica. A cache não é indexada pelo utilizador delegado; mantenha um mapeamento explícito de utilizador para sessão ao usar --user-identity.

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.

Resource O que é Gerenciado com
Connection Liga um projeto Foundry a um recurso externo, como um servidor MCP, Pesquisa de IA do Azure ou Grounding com Bing. azd ai connection comandos
Caixa de ferramentas Uma coleção nomeada de ferramentas que os agentes usam em tempo de execução. azd ai toolbox comandos
Competência Uma diretriz comportamental reutilizável partilhada entre os agentes do projeto. azd ai skill comandos
Rotina Um gatilho mais uma ação que invoca um agente. azd ai routine comandos

Estes recursos são partilhados entre programadores e agentes no mesmo projeto. Os seus comandos diferem: as ligações e rotinas têm update, as skills publicam uma nova versão através de update, e as toolboxes usam mutações de ligação e skills que produzem versões seguidas de publish.

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 rápida do agente utiliza azd ai agent eval e um eval.yaml local, incluindo o fluxo de trabalho do otimizador. A avaliação do projeto utiliza a extensão instalada separadamente azd ai eval e evals/azure.eval.yaml, com fontes de rastreio ou de conjunto de dados e gates de qualidade de CI explícitos. Os dois formatos de configuração não são intercambiáveis.
  • 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.

Grupos de comandos por função do programador

Escolhe um comando para o resultado que precisas. Anexe --help para inspecionar as suas flags e formatos de saída suportados.

Job Commands Guidance
Configurar um projeto e os modelos geridos azd ai project add, azd ai project deployment add Configuração e contexto do projeto
Selecionar ou inspecionar o contexto do endpoint azd ai project set, azd ai project show, azd ai project unset, azd ai project context A seleção global de endpoints é separada das declarações de infraestrutura. A saída de contexto pode conter segredos.
Explore amostras ou inicie um agente azd ai agent sample list, azd ai agent init, azd ai agent add Inicialize os agentes alojados, de prompt e de voz
Processar sintaticamente, extrair e classificar documentos e conteúdos para agentes azd ai cu analyze, azd ai cu analyzer Início rápido da CLI do Azure Content Understanding (pré-visualização)
Executar e inspecionar localmente azd ai agent run, azd ai inspector launch Desenvolvimento local
Invocar, delegar a identidade do utilizador ou enviar cabeçalhos personalizados azd ai agent invoke Opções de invocação
Inspecionar, acompanhar ou cancelar trabalho azd ai agent invocations show, azd ai agent invocations follow, azd ai agent invocations cancel Invocação de longa duração
Ver ou atualizar um endpoint azd ai agent endpoint show, azd ai agent endpoint update Atualizações de Endpoint e cards
Inspecionar o estado, diagnosticar problemas ou ler registos azd ai agent show, azd ai agent doctor, azd ai agent monitor Diagnósticos e registos
Criar, listar, inspecionar, parar ou eliminar um sandbox azd ai agent sessions create, azd ai agent sessions list, azd ai agent sessions show, azd ai agent sessions stop, azd ai agent sessions delete Gestão de sessões
Carregar, recuperar ou manter ficheiros da sandbox azd ai agent files upload, azd ai agent files download, azd ai agent files list, azd ai agent files mkdir, azd ai agent files stat, azd ai agent files delete Operações de ficheiros de sessão
Recuperar o código-fonte implementado azd ai agent code download Transferir código ou um ficheiro ZIP
Inspecionar armazenamentos duráveis e manter os itens partilhados azd ai agent state-stores list, azd ai agent state-stores select, azd ai agent state-stores show, azd ai agent state-stores items Operações e limites do armazenamento de estado
Adicionar dependências do agente à configuração de implantação azd ai agent connection add, azd ai agent toolbox add Ambos os serviços devem já existir em azure.yaml; estes comandos adicionam uses entradas, não recursos remotos.
Gerir credenciais de ligação e metadados azd ai connection create, azd ai connection list, azd ai connection show, azd ai connection update, azd ai connection delete Autenticação e manutenção da ligação
Autor, versão ou descarregar competências reutilizáveis azd ai skill add, azd ai skill create, azd ai skill update, azd ai skill list, azd ai skill show, azd ai skill download, azd ai skill delete Fluxos de trabalho de competências
Criar, editar e gerir conjuntos de ferramentas azd ai toolbox add, azd ai toolbox create, azd ai toolbox list, azd ai toolbox show, azd ai toolbox delete Configuração da caixa de ferramentas
Evoluir e promover coleções de ferramentas azd ai toolbox connection, azd ai toolbox skill, azd ai toolbox versions list, azd ai toolbox publish As mutações ramificam-se a partir da versão mais recente; a promoção é explícita.
Programar, despachar ou inspecionar rotinas azd ai routine add, azd ai routine create, azd ai routine show, azd ai routine list, azd ai routine update, azd ai routine run list, azd ai routine disable, azd ai routine dispatch, azd ai routine enable, azd ai routine delete Fluxos de trabalho rotineiros
Gerar e executar uma avaliação rápida azd ai agent eval generate, azd ai agent eval update, azd ai agent eval run, azd ai agent eval list, azd ai agent eval show Avaliação rápida e recursos de otimização
Melhorar e implementar um candidato à otimização azd ai agent optimize, azd ai agent optimize status, azd ai agent optimize list, azd ai agent optimize cancel, azd ai agent optimize apply, azd ai agent optimize deploy Fluxo de trabalho de otimização
Criar pacote ou publicar um agente de atividade para Teams azd ai agent pack, azd ai agent publish Distribuição das equipas
Eliminar uma versão hospedada ou um agente azd ai agent delete Eliminação de agente
Avaliar um projeto e aplicar portões de qualidade azd ai eval init, azd ai eval generate, azd ai eval create, azd ai eval run, azd ai eval dataset, azd ai eval evaluator, azd ai eval job Avaliação do projeto; instalar azure.ai.evaluations separadamente.
Conjuntos de dados reutilizáveis de registo e versão azd ai dataset Ciclo de vida do conjunto de dados; instalar azure.ai.dataset separadamente.
Submeter, pausar, retomar, cancelar ou implementar trabalhos de ajuste fino azd ai finetuning init, azd ai finetuning jobs Ajuste; instale azure.ai.finetune separadamente.
Enviar e gerir pesos personalizados de modelos azd ai models Importação e manutenção de modelos personalizados; instalar azure.ai.models separadamente.

Cada extensão que adiciona comandos expõe version; inspecione o bundle microsoft.foundry com azd ext list em vez disso. Os grupos de ligação, rotina e competências também disponibilizam context para inspeção do projeto local e do ambiente; trate o resultado como potencialmente sensível.

Distribuição de agentes de atividade

Após a implementação de um agente Activity-protocol, este cria azd ai agent packappPackage.zip para sideloading. Utilize --output-dir, --display-name e --app-version para personalizar o pacote. O empacotamento não é o mesmo que a publicação.

azd ai agent publish publica através de Microsoft 365. Os agentes Simple Activity por defeito usam distribuição shared , salvo configuração de outra forma; --scope tenant requer aprovação do administrador. Os Trabalhadores Digitais exigem âmbito do tenant. Utilize valores repetíveis --access-boundary, --clear-access-boundaries para remover limites existentes e valores repetíveis --optional-permission-scope <resource-app-id>=<scope> para permissões opcionais. personal não é um escopo de publicação; usa pack --scope personal e carrega lateralmente o pacote para testes por utilizador.

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