Referência azure.yaml para agentes hospedados

O azure.yaml ficheiro é a configuração única do projeto Azure Developer CLI (azd) para um projeto de agente hospedado. Declara os seus recursos Foundry — o projeto, implementações de modelos, ligações, caixas de ferramentas, competências, rotinas e os próprios agentes — como um conjunto de serviços, e indica azd como os provisionar e implementar. Este ficheiro unificado substitui o modelo anterior de dois ficheiros que dividia a configuração entre agent.manifest.yaml e agent.yaml.

Para aprender a compor e criar este ficheiro passo a passo, consulte Author azure.yaml para agentes alojados.

Como o azd usa o azure.yaml

A CLI do Azure Developer simplifica o fluxo de trabalho do programador para a cloud. Trata de duas coisas: o provisionamento de recursos do Azure, como projetos Foundry, implementações de modelos e registos de contentores; e a implementação do teu código nesses recursos. Para agentes alojados, a azure.ai.agents extensão adiciona comandos específicos do agente, como azd ai agent init e azd ai agent run.

Cada azd projeto tem um azure.yaml ficheiro na sua raiz. Para projetos de agentes, este ficheiro é a fonte de verdade tanto para a configuração do agente como para a configuração de implementação.

Environments

Um ambiente é uma configuração nomeada, como dev, staging, ou prod, que armazena definições para uma implementação específica. Cada ambiente acompanha a subscrição e localização do Azure, o grupo de recursos e os nomes dos recursos, e quaisquer variáveis personalizadas que definas. As definições são armazenadas localmente em .azure/<env-name>/.env. Podes ter vários ambientes para o mesmo projeto.

Comandos principais

Compatibilidade de extensões

A azure.ai.agents extensão fornece o azure.ai.agent hospedeiro. A azure.ai.projects extensão fornece o azure.ai.project host e o fornecedor de microsoft.foundry infraestrutura. Use azure.ai.agents a versão 1.0.0-beta.8 ou mais tarde com azure.ai.projects a versão 1.0.0-beta.4 ou mais tarde. Para instruções de instalação e atualização, consulte Instalar as extensões do Azure Developer CLI Foundry.

Pode declarar as versões mínimas compatíveis em azure.yaml:

requiredVersions:
    azd: ">=1.27.1"
    extensions:
        azure.ai.agents: ">=1.0.0-beta.8"
        azure.ai.projects: ">=1.0.0-beta.4"

Ciclo de vida do fornecedor de serviços

Instale o microsoft.foundry meta-pacote quando o seu projeto incluir ligações, caixas de ferramentas, competências ou rotinas. Instala as extensões do fornecedor que implementam os hosts correspondentes azure.ai.* .

O projeto e os fornecedores de ligação aplicam a sua configuração durante azd provision. O agente, caixa de ferramentas, competências e fornecedores rotineiros aplicam a sua configuração durante azd deploy. Corre azd up para completar ambas as fases. Remover um serviço de data-plane impede azure.yamlazd a sua gestão; apague o recurso remoto separadamente quando já não precisar dele.

• azd down - Elimina o grupo de recursos quando o ambiente atual criou o projeto Foundry. Deixa um projeto existente e os seus recursos no local. |
• azd env set - Define uma variável de ambiente, por exemplo azd env set FOUNDRY_MODEL_NAME=gpt-5.4-mini. |

O modelo de serviço dividido

Sob services, cada entrada é um serviço nomeado com um host campo que identifica o tipo de recurso da Foundry que declara. Os serviços referenciam-se mutuamente através do uses campo, que forma um grafo de dependência que azd se resolve no momento da provisão e da implementação. Um projeto típico tem um azure.ai.project serviço que detém as implementações do modelo e um azure.ai.agent serviço que depende dele.

Exemplo mínimo

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
name: my-agent-project

services:
    ai-project:
        host: azure.ai.project
        deployments:
            - name: gpt-5.4-mini
              model:
                format: OpenAI
                name: gpt-5.4-mini
                version: "2026-03-17"
              sku:
                name: GlobalStandard
                capacity: 10

    my-agent:
        host: azure.ai.agent
        project: src/my-agent
        language: docker
        uses:
            - ai-project
        kind: hosted
        name: my-agent
        description: A hosted agent built from source.
        protocols:
            - protocol: responses
              version: 2.0.0
        env:
            MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
        container:
            resources:
                cpu: "0.25"
                memory: 0.5Gi

Exemplo completo

O projeto seguinte acrescenta uma ligação, uma caixa de ferramentas e redes privadas.

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
requiredVersions:
    extensions:
        azure.ai.agents: '>=0.1.0-preview'

name: research-agent-project

services:
    ai-project:
        host: azure.ai.project
        deployments:
            - name: gpt-5.4-mini
              model:
                format: OpenAI
                name: gpt-5.4-mini
                version: "2026-03-17"
              sku:
                name: GlobalStandard
                capacity: 50

    search-conn:
        host: azure.ai.connection
        uses:
            - ai-project
        category: CognitiveSearch
        target: https://my-search.search.windows.net
        authType: ApiKey
        credentials:
            key: ${SEARCH_API_KEY}

    research-tools:
        host: azure.ai.toolbox
        uses:
            - ai-project
            - search-conn
        description: Tools used by the research agent.
        tools:
            - type: azure_ai_search
              connection: search-conn
            - type: code_interpreter

    researcher:
        host: azure.ai.agent
        project: src/researcher
        language: docker
        uses:
            - ai-project
            - search-conn
            - research-tools
        kind: hosted
        name: researcher
        description: Hosted research agent built from source.
        startupCommand: python main.py
        toolboxes:
            - research-tools
        env:
            LOG_LEVEL: info
        protocols:
            - protocol: responses
              version: 2.0.0
        container:
            resources:
                cpu: "1.0"
                memory: 2Gi

infra:
    provider: bicep
    path: ./infra

Campos de nível superior

serviço azure.ai.project

O projeto presta serviços ou liga-se a um projeto Foundry e detém as suas implementações modelo.

deployments

Uma entrada de implementação pode também ser um ficheiro externo que inclui: - $ref: ./deployments/embeddings.yaml.

rede

Configurar network para provisionar uma conta segura em rede. O peSubnet campo é obrigatório e estabelece o endpoint privado da conta. Adiciona agentSubnet para injetar o runtime do agente na tua própria sub-rede (traz a tua própria rede virtual), ou omite-o para usar a rede gerida pela Microsoft. Para um guia completo, consulte Networking privado de agentes alojados.

Configuração de rede privada

Use network no azure.ai.project serviço para configurar o endpoint privado da conta e a saída do agente. O exemplo seguinte utiliza uma sub-rede gerida pelo cliente para o tempo de execução do agente:

services:
    ai-project:
        host: azure.ai.project
        network:
            peSubnet:
                vnet: ${VNET_RESOURCE_ID}
                name: private-endpoint-subnet
            agentSubnet:
                vnet: ${VNET_RESOURCE_ID}
                name: agent-subnet
            dns:
                resourceGroup: ${PRIVATE_DNS_RESOURCE_GROUP}
                subscription: ${PRIVATE_DNS_SUBSCRIPTION_ID}

A rede privada desativa o acesso ao plano de dados público da conta. Um Azure Container Registry criado automaticamente não é suportado com esta configuração. Use a implementação do código-fonte ou especifique um arquivo pré-construído image.

azure.ai.agent service

O serviço de agente transporta a definição do agente e as suas definições de build e deploy. É o serviço que substitui o antigo agent.yaml.

agentCard.skills e azure.ai.skill

agentCard.skills descreve as capacidades de um agente no seu cartão de descoberta. Fornece metadados para os clientes e não cria nem anexa uma competência reutilizável do Foundry. Cada habilidade de carta requer um id, name, e description.

Um azure.ai.skill serviço cria uma competência versionada a partir de instruções e ferramentas opcionais permitidas. Declara-a separadamente sob services; a sua uses lista controla a ordem das dependências, mas não preenche agentCard.skills nem anexa a habilidade a um agente. Use agentCard.skills para metadados de descoberta e azure.ai.skill para instruções reutilizáveis.

agentCard:
    description: Research agent discovery card.
    skills:
        - id: research
          name: Research
          description: Researches a requested subject.

services:
    code-review:
        host: azure.ai.skill
        uses:
            - ai-project
        instructions: ./skills/code-review.md

Preencha um cartão de descoberta

Adicione version, tags, e examples quando os clientes precisam de metadados de descoberta mais ricos. Uma carta requer uma description e pelo menos uma habilidade. Cada habilidade requer um id, name, e description.

agentCard:
    description: Research agent discovery card.
    version: "1.0"
    skills:
        - id: research
          name: Research
          description: Researches a requested subject.
          tags:
              - research
          examples:
              - Research current product guidance.

Políticas de IA responsável

Use policies para associar uma política de IA responsável ao agente alojado. Definir raiPolicyName para o ID completo do recurso ARM da política:

policies:
    - type: rai_policy
      raiPolicyName: ${RAI_POLICY_RESOURCE_ID}

O rai_policy tipo e raiPolicyName são obrigatórios. A extensão aplica a primeira política válida da lista à configuração Responsible AI com agente hospedado. Para orientações sobre criação e gestão de políticas, consulte Adicionar guarda-limites aos agentes alojados.

Armazenamentos de memória

Use memoryStores para criar ou reutilizar memórias do Foundry antes da implementação. Cada loja requer nomes de implementação existentes para modelos de chat e modelos de embedding.

memoryStores:
    - name: customer-memory
      description: Stores durable customer context.
      chatModel: gpt-5.4-mini
      embeddingModel: text-embedding-3-large
      options:
          chatSummaryEnabled: true
          userProfileEnabled: true
          proceduralMemoryEnabled: false
          defaultTtlSeconds: 0

As lojas existentes não são atualizadas durante a implementação. Se a definição declarada difere da loja existente, reporta azd a diferença. Declarar um armazenamento de memória não altera o seu código de agente nem anexa automaticamente uma ferramenta de memória. Ligue a sua aplicação à memória usando a ferramenta de pesquisa de memória ou as APIs de memória. Para detalhes, veja Usar memória com agentes.

Configurar um endpoint de agente

Use agentEndpoint para configurar os protocolos e esquemas de autorização publicados pelo endpoint do agente. Use um cartão de agente com um endpoint A2A para que outros agentes possam descobrir as capacidades que expõe.

agentEndpoint:
    protocols:
        - responses
        - a2a
    authorizationSchemes:
        - type: Entra

Também podes definir versionSelector.versionSelectionRules quando precisas de controlar qual versão do agente recebe tráfego de endpoint. O Serviço Agente valida os valores do protocolo e autorização do endpoint durante a implementação.

protocols

protocols:
    - protocol: responses
      version: 2.0.0

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

Protocolos de execução adicionais e endpoints de Atividade

Além de responses, , e a2a, suporte de agentes invocations_ws hospedados para invocações WebSocket e activity para cenários de atividade do Microsoft 365 invocationse Teams.

protocols:
    - protocol: invocations_ws
      version: 2.0.0
    - protocol: activity
      version: 2.0.0

Para um agente de Atividade, adicione activity à configuração do endpoint público e use o esquema de autorização exigido do Bot Service:

agentEndpoint:
    protocols:
        - activity
    authorizationSchemes:
        - type: BotServiceRbac

O protocolo Activity pode coexistir com outros protocolos no mesmo endpoint agente. Para o comportamento do protocolo em tempo de execução, veja O que são agentes alojados?.

env

env:
    MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
    LOG_LEVEL: info

A ${ } sintaxe faz referência azd a variáveis de ambiente a partir de .azure/<env>/.env.

Ambiente da plataforma, identidade e endpoints

A plataforma reserva os FOUNDRY_ prefixos e AGENT_ . Leia variáveis de plataforma, como FOUNDRY_PROJECT_ENDPOINT, a partir do seu código de aplicação, mas não as defina nem sobrepone em env. Os valores do ambiente definidos pelo agente são cadeias de caracteres.

Cada agente alojado implementado recebe uma identidade e endpoint dedicado de agente Microsoft Entra ID. Não adicione um identity bloqueio ao serviço de agentes. A identidade do agente pode usar o endpoint do projeto e o armazenamento da sessão por defeito. Atribuir à identidade papéis adicionais quando o agente precisar de aceder a recursos externos. Para mais detalhes, consulte Referência de permissões do agente alojado.

Os protocolos que declaras determinam os endpoints que ficam ativos após a implementação. Execute azd ai agent show para inspecionar o agente implementado e as URLs dos seus endpoints.

Após a implementação, azd escreve os seguintes valores no ambiente ativo, usando o nome normalizado do serviço em vez de <SERVICE>:

• AGENT_<SERVICE>_NAME
• AGENT_<SERVICE>_VERSION
• AGENT_<SERVICE>_ENDPOINT
• AGENT_<SERVICE>_<PROTOCOL>_ENDPOINT para ativados responses, invocations, e invocations_ws protocolos

Use a saída específica do protocolo quando a sua aplicação ou automação precisar de um URL de invocação. O endpoint base identifica a versão do agente implementado para operações de gestão de sessões.

contentor

container:
    resources:
        cpu: "0.25"
        memory: 0.5Gi

Defina cpu de "0.25" até "4.0", e memory de 0.5Gi até 8.0Gi.

Implementação do código-fonte

Definir codeConfiguration para implementar o código-fonte como uma imagem ZIP em vez de uma imagem de contentor. Especifique um nome de ficheiro ou nome de montagem para um ponto de entrada. azd combina com o runtime selecionado quando cria a versão hosted-agent.

codeConfiguration:
    runtime: python_3_13
    entryPoint: main.py
    dependencyResolution: remote_build

remote_build Use para restaurar dependências das fontes do projeto, ou use bundled quando o ZIP contém dependências compatíveis com Linux. Não combines codeConfiguration com a configuração de contentores baseada em imagem. Para orientações sobre empacotamento e dependências, veja Deploy a hosted agent from source code.

Builds de contentores e imagens pré-construídas

Use um Dockerfile under project para construir uma imagem de contentor, ou configure image para implementar uma imagem pré-construída:

image: myregistry.azurecr.io/agents/researcher:1.2.3

Quando a Dockerfile e an image estiverem ambos disponíveis, escolha a imagem pré-construída no prompt de implementação interativa. Para implementação não assistida, defina AZD_AGENT_SKIP_ACR para true no ambiente ativo azd para selecionar a imagem configurada. Para permissões de registo e implementação de registos privados, veja Deploy a hosted agent with a private Azure Container Registry.

Metadados e limitações de esquema

Use valores de cadeia para metadados de agentes implementados. O authors valor dos metadados pode ser uma lista de cadeias de caracteres. Não confie em displayName, inputSchema, nem outputSchema para configurar o agente hospedado implementado; a configuração unificada aceita estes campos, mas o pedido de criação do agente hospedado não os utiliza.

azure.ai.connection service

Uma ligação liga o projeto a um recurso externo. A chave de serviço é o nome da ligação, e o serviço depende do projeto através de uses.

github-conn:
    host: azure.ai.connection
    uses:
        - ai-project
    category: RemoteTool
    target: https://api.githubcopilot.com/mcp
    authType: CustomKeys
    credentials:
        Authorization: ${GITHUB_PAT}

As alterações de ligação aplicam-se durante azd provision, não azd deploy. Armazene valores de credencial no seu azd ambiente e faça referência a eles com ${VAR} , em vez de colocar segredos em azure.yaml.

serviço azure.ai.toolbox

Uma caixa de ferramentas é um conjunto nomeado de ferramentas que os agentes referenciam. Ferramentas apoiadas por ligação nomeiam um azure.ai.connection serviço através do connection campo.

research-tools:
    host: azure.ai.toolbox
    uses:
        - ai-project
        - search-conn
    tools:
        - type: azure_ai_search
          connection: search-conn
        - type: code_interpreter

Um agente referencia uma toolbox adicionando o nome do serviço toolbox a ambos uses e à sua toolboxes lista.

Consume um endpoint toolbox

Num projeto de serviço dividido, uses controla a ordem de implementação. A sua aplicação liga-se ao endpoint MCP da toolbox em tempo de execução. Passe o nome da toolbox ou endpoint à sua aplicação através de env, depois construa o endpoint de consumidor a FOUNDRY_PROJECT_ENDPOINT partir do código do seu agente. Para um exemplo de ponta a ponta, veja Usar uma caixa de ferramentas com um agente alojado.

serviços azure.ai.skill e azure.ai.routine

Um serviço define uma diretriz comportamental reutilizável que os agentes referenciam azure.ai.skill pelo nome. Um azure.ai.routine serviço define um gatilho (agendamento ou evento) e uma ação que invoca um agente. Ambos dependem dos recursos que utilizam através usesde . Para saber mais sobre como adicionar ferramentas para uso de agentes, veja O que é o Toolbox no Foundry? e Use rotinas.

Competências e rotinas são recursos separados. Declarar qualquer um dos serviços controla o seu ciclo de vida, mas não atribui automaticamente uma habilidade ao agente nem infire um alvo de ação rotineiro. Configure explicitamente a aplicação ou ação rotineira que consome o consumidor.

Dependências com utilizações

O uses campo declara os serviços de que um dado serviço depende. azd Utiliza este grafo para ordenar o provisionamento e para referenciar fios, como as ligações e caixas de ferramentas de um agente.

uses:
    - ai-project
    - search-conn
    - research-tools

Inclui ficheiros com $ref

Qualquer entrada de serviço ou lista pode ser substituída por uma referência a um ficheiro YAML ou JSON externo. Os caminhos relativos resolvem-se a partir do ficheiro que contém o $ref. URLs remotas não são suportadas.

services:
    triage:
        host: azure.ai.agent
        uses:
            - ai-project
        $ref: ./agents/triage.yaml

O file includes permite manter definições de agentes grandes nos seus próprios ficheiros e partilhar definições entre projetos.

Mantenha os campos do serviço central na entrada raiz azure.yaml quando usar um serviço $ref: host, uses, project, language, image, , e docker. Coloque campos de definição pertencentes ao fornecedor, como kind, name, description, e protocols, no mapeamento referenciado. $ref resolve ficheiros locais YAML ou JSON recursivamente; URLs e ciclos de referência não são suportados.

Substituição de variáveis

Duas sintaxes de substituição podem aparecer em azure.yaml:

Infraestrutura e modos de implementação

Sem Bicep por defeito

azd ai agent init é sem bíceps por defeito: não escreve um infra/ diretório e azd sintetiza a infraestrutura dos seus azure.yaml serviços no momento da provisão. Para materializar ficheiros infraestrutura como código, ejete-os:

Quando infra está presente em azure.yaml, azd utiliza esses ficheiros em vez de sintetizar a infraestrutura.

Modos de implantação

Um agente hospedado é implementado em dois modos:

Para deploys de código-fonte, o codeConfiguration campo no serviço agente capta o tempo de execução e o ponto de entrada. Para imagens pré-construídas, defina o image campo no serviço agente e ignore a compilação Dockerfile.

Migração de configuração legada

Definições antigas de agentes podem aninhar variáveis de ambiente sob config: env. No unificado azure.yaml, move o env mapeamento para o serviço agente:

# Legacy
services:
    my-agent:
        host: azure.ai.agent
        config:
            env:
                MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}

# Unified azure.yaml
services:
    my-agent:
        host: azure.ai.agent
        env:
            MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}

Validação de esquema JSON

Adicione a referência de esquema para a autocompletação do IDE:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json

Conteúdo relacionado

• Autor azure.yaml para agentes alojados
• Inicializar um projeto de agente hospedado com a CLI Azure Developer
• Infraestrutura de agente hospedado com o Azure Developer CLI
• Contrato de execução de agente hospedado
• O que são agentes hospedados?