Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Importante
Os itens marcados como visualização neste artigo estão atualmente em versão prévia. Esta versão prévia é fornecida sem um contrato de nível de serviço (SLA), e a Microsoft não a recomenda para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft 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.
| Stage | O que você faz | Onde saber mais |
|---|---|---|
| Install | Instale azd e as extensões do Foundry. |
Configurar seu ambiente de desenvolvedor |
| Scaffold | Inicialize um agente hospedado a partir de um modelo ou do seu código existente, ou crie um agente de voz baseado em prompt. | Início Rápido: Implantar um agente hospedado ou Início Rápido: Criar um agente de voz com prompt |
| Definir | Configure o agente, as dependências de implantação do modelo, os protocolos, as ferramentas e o ambiente em azure.yaml. |
Criar azure.yaml para agentes hospedados |
| Develop | Escreva a lógica do agente, adicione ferramentas usando uma caixa de ferramentas e teste localmente. | Visão geral da caixa de ferramentas |
| Deploy | Provisione a infraestrutura e implante no Foundry. | Implantar um agente hospedado |
| Operar | Monitorar logs, gerenciar versões e automatizar execuções. | Gerenciar agentes hospedados |
| Evaluate | Medir a qualidade do agente e melhorar o prompt. | Executar avaliações de agente com a CLI do azd |
Tipos de agente
A extensão azd ai agent oferece suporte a agentes hospedados, de prompt e de voz.
| Tipo | Description | Quando usar |
|---|---|---|
| Agente hospedado | Um aplicativo que você implanta como código-fonte ou uma imagem de contêiner. | Você precisa de lógica personalizada, integração de estrutura ou controle total sobre o comportamento. |
| Agente de prompt | Um agente definido inteiramente por meio de instruções e configurações de ferramentas, sem código personalizado. | Você deseja um agente rápido e controlado por configurações sem escrever o código do aplicativo. |
| Agente de voz | Um agente de voz de prompt declarativo ou um wrapper de voz que se conecta a um agente hospedado. | Você precisa de uma experiência de voz em tempo real por meio de um cliente do Voice Live. |
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.
| File | Purpose | Quem o mantém |
|---|---|---|
azure.yaml |
Declara o projeto foundry, implantações de modelo, serviço de agente hospedado, dependências, protocolos, ferramentas, variáveis de ambiente, recursos de contêiner e configurações de implantação. Identidade, modelo, protocolos, ferramentas e valores de ambiente do agente residem no azure.ai.agent serviço. |
A inicialização o gera. Você o personaliza conforme necessário. |
O serviço azure.ai.agent define seu agente diretamente em linha ou por meio de uma raiz explícita $ref para uma definição YAML ou JSON direta. Use azd ai agent add <service> --file <path> para um serviço baseado em arquivo. Wrappers parametrizados AgentManifest não são compatíveis com a inicialização atual. A lista de uses: do serviço faz referência a dependências como o projeto, conexões e caixas de ferramentas.
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 ambienteazdativo. - Fora de um projeto
azd, defina o contexto ativo uma vez comazd ai project set <endpoint>ou passe--project-endpointem um comando de recurso individual (connection,toolbox,skillouroutine). Como alternativa,azd ailê a variável de ambienteFOUNDRY_PROJECT_ENDPOINT. - Um endpoint não vazio resolvido do ambiente ativo tem precedência sobre o contexto global. Para comportamento alternativo ao shell e específico de comandos, consulte Definir o contexto do 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.
| Protocol | Estilo de API | Quando usar |
|---|---|---|
responses |
API de Respostas do OpenAI (POST /responses) |
A opção padrão, compatível com o ecossistema da API OpenAI. |
invocations |
Contrato JSON personalizado (POST /invocations) |
Quando você precisa de controle total sobre as cargas de solicitação e resposta. |
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
| Conceito | Description |
|---|---|
| Session | Um ambiente de execução isolado para uma única interação de agente. Cada sessão é executada em sua própria área restrita com recursos dedicados. |
| Conversa | Histórico de mensagens para o protocolo Respostas. As invocações não persistem automaticamente o histórico de conversas. |
As sessões são identificadas por um session_id. A CLI salva a seleção de sessão por agente e a reutiliza por padrão. Use --new-session para iniciar novamente ou --session-id <id> para direcionar uma sessão específica. O cache não é chaveado pelo usuário delegado; manter um mapeamento de usuário para sessão explícito ao usar --user-identity.
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.
| Resource | O que é | Gerenciado com |
|---|---|---|
| Connection | Vincula um projeto do Foundry a um recurso externo, como um servidor MCP, o Pesquisa de IA do Azure ou o Grounding with Bing. |
azd ai connection comandos |
| Caixa de Ferramentas | Uma coleção nomeada de ferramentas que os agentes usam em runtime. |
azd ai toolbox comandos |
| Habilidade | Uma diretriz comportamental reutilizável compartilhada entre agentes no projeto. |
azd ai skill comandos |
| Rotina | Um gatilho mais uma ação que invoca um agente. |
azd ai routine comandos |
Esses recursos são compartilhados entre desenvolvedores e agentes no mesmo projeto. Seus comandos diferem: conexões e rotinas têm update, habilidades publicam uma nova versão por meio de update, e caixas de ferramentas usam mutações de conexão e habilidade que produzem versão, seguidas por publish.
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 rápida do agente usa
azd ai agent evale umeval.yamllocal, incluindo o fluxo de trabalho do otimizador. A avaliação do projeto usa a extensãoazd ai evalinstalada separadamente eevals/azure.eval.yaml, com fontes de rastreamento 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 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.
Grupos de comandos por tarefa do desenvolvedor
Escolha um comando para obter o resultado desejado. Adicione --help ao comando para inspecionar seus sinalizadores e formatos de saída com suporte.
| Job | Commands | Guidance |
|---|---|---|
| Configurar um projeto e modelos gerenciados |
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 de ponto de extremidade global é separada das declarações de infraestrutura. A saída do contexto pode conter segredos. |
| Procurar exemplos ou inicializar um agente |
azd ai agent sample list, azd ai agent init, azd ai agent add |
Inicializar agentes hospedados, de prompt e de voz |
| Analisar, extrair e classificar documentos e conteúdo para agentes |
azd ai cu analyze, azd ai cu analyzer |
início rápido da CLI do Azure Content Understanding (versão prévia) |
| Executar e inspecionar localmente |
azd ai agent run, azd ai inspector launch |
Desenvolvimento local |
| Invocar, delegar identidade do usuário ou enviar cabeçalhos personalizados | azd ai agent invoke |
Opções de invocação |
| Inspecionar, acompanhar ou cancelar tarefas |
azd ai agent invocations show, azd ai agent invocations follow, azd ai agent invocations cancel |
Invocação de longa duração |
| Inspecionar ou atualizar um endpoint |
azd ai agent endpoint show, azd ai agent endpoint update |
Atualizações de pontos de extremidade e cartões |
| Inspecionar status, diagnosticar problemas ou ler logs |
azd ai agent show, azd ai agent doctor, azd ai agent monitor |
Diagnósticos e logs |
| Criar, listar, inspecionar, parar ou excluir 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 |
Gerenciamento de sessão |
| Inicializar, recuperar ou manter arquivos de 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 arquivo de sessão |
| Recuperar código-fonte implantado | azd ai agent code download |
Baixar código ou um ZIP |
| Inspecionar repositórios duráveis e manter itens compartilhados |
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 repositório de estado |
| Adicionar dependências de agente à configuração de implantação |
azd ai agent connection add, azd ai agent toolbox add |
Ambos os serviços já devem existir em azure.yaml; esses comandos adicionam entradas uses, não recursos remotos. |
| Gerenciar credenciais de conexã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 de conexão |
| Criar, versionar ou baixar habilidades 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 habilidades |
| Criar e gerenciar toolboxes |
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 são ramificadas a partir da versão mais recente; a promoção é explícita. |
| Agendar, despachar ou inspecionar rotinas |
azd ai routine add, azd ai routine create, azd ai routine list, azd ai routine show, azd ai routine update, , azd ai routine enable, azd ai routine disable, , azd ai routine dispatch, azd ai routine run list, 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 |
| Aprimorar e implantar 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 |
| Empacotar ou publicar um agente de Atividade para o Teams |
azd ai agent pack, azd ai agent publish |
Distribuição do Teams |
| Excluir uma versão hospedada ou um agente | azd ai agent delete |
Exclusão do agente |
| Avaliar um projeto e aplicar critérios 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; instale azure.ai.evaluations separadamente. |
| Registrar e versionar conjuntos de dados reutilizáveis | azd ai dataset |
Ciclo de vida do conjunto de dados; instalar azure.ai.dataset separadamente. |
| Enviar, pausar, retomar, cancelar ou implantar tarefas de ajuste fino |
azd ai finetuning init, azd ai finetuning jobs |
Ajuste fino; instalar azure.ai.finetune separadamente. |
| Carregar e gerenciar pesos de modelo personalizado | azd ai models |
Importação e manutenção de modelo personalizado; instalar azure.ai.models separadamente. |
Cada extensão que adiciona comandos expõe version; inspecione o pacote microsoft.foundry com azd ext list em vez disso. Os grupos de conexão, rotina e habilidade também expõem context para inspeção local de projeto e ambiente; trate a saída como potencialmente sensível.
Distribuição do agente de atividade
Após implantar um agente de protocolo de atividade, azd ai agent pack cria appPackage.zip para carregamento lateral. Use --output-dir, --display-name e --app-version para personalizar o pacote. Empacotar não é o mesmo que publicar.
azd ai agent publish publica por meio do Microsoft 365. Os agentes de atividade simples usam a distribuição shared por padrão, a menos que configurados de outra forma; --scope tenant requer aprovação do administrador. Trabalhadores Digitais exigem escopo de locatário. Use valores --access-boundary repetíveis, --clear-access-boundaries para remover limites existentes e valores --optional-permission-scope <resource-app-id>=<scope> repetíveis para permissões opcionais.
personal não é um escopo de publicação; use pack --scope personal e faça o sideload do pacote para testes por usuário.
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