referência azure.yaml para agentes hospedados

O azure.yaml arquivo é a única configuração de projeto da CLI do Desenvolvedor do Azure (azd) para um projeto de agente hospedado. Ele declara seus recursos do Foundry – o projeto, implantações de modelo, conexões, caixas de ferramentas, habilidades, rotinas e os próprios agentes – como um conjunto de serviços e informa azd como provisioná-los e implantá-los. Esse arquivo unificado substitui o modelo anterior de dois arquivos que divide a configuração entre agent.manifest.yaml e agent.yaml.

Para saber como redigir e criar este arquivo passo a passo, consulte Author azure.yaml para agentes hospedados.

Como o azd usa azure.yaml

A CLI do desenvolvedor Azure simplifica o fluxo de trabalho do desenvolvedor para a nuvem. Ele lida com duas coisas: provisionar Azure recursos, como projetos de Foundry, implantações de modelo e registros de contêiner; e implantar seu código nesses recursos. Para agentes hospedados, 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 arquivo em sua raiz. Para projetos de agente, esse arquivo é a fonte da verdade tanto para a configuração do agente quanto para a configuração de implantação.

Environments

Um ambiente é uma configuração nomeada, como dev, stagingou prod, que armazena configurações para uma implantação específica. Cada ambiente controla a assinatura e a localização Azure, o grupo de recursos e os nomes de recursos e as variáveis personalizadas definidas. As configurações são armazenadas localmente em .azure/<env-name>/.env. Você pode ter vários ambientes para o mesmo projeto.

Comandos principais

Compatibilidade de extensão

A azure.ai.agents extensão fornece o azure.ai.agent host. A azure.ai.projects extensão fornece o azure.ai.project host e o provedor de microsoft.foundry infraestrutura. Use azure.ai.agents a versão 1.0.0-beta.8 ou posterior com azure.ai.projects versão 1.0.0-beta.4 ou posterior. Para obter instruções de instalação e atualização, consulte Instalar as extensões da CLI do desenvolvedor do Azure.

Você 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 provedor de serviços

Instale o microsoft.foundry metapacote quando o projeto incluir conexões, caixas de ferramentas, habilidades ou rotinas. Ele instala as extensões de provedor que implementam os hosts correspondentes azure.ai.* .

Os provedores de projeto e conexão aplicam sua configuração durante azd provision. Os provedores de agente, caixa de ferramentas, habilidade e rotina aplicam sua configuração durante azd deploy. Execute azd up para concluir ambas as fases. Remover um serviço de plano de dados de azure.yaml paradas azd de gerenciá-lo; exclua o recurso remoto separadamente quando você não precisar mais dele.

• azd down – Exclui o grupo de recursos quando o ambiente atual criou o projeto Foundry. Deixa um projeto existente e seus recursos em vigor. |
• 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

Em , servicescada entrada é um serviço nomeado com um host campo que identifica o tipo de recurso foundry que ele declara. Os serviços fazem referência uns aos outros por meio do uses campo, que forma um grafo de dependência que azd é resolvido no tempo de provisionamento e implantação. Um projeto típico tem um azure.ai.project serviço que possui as implantações de 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 a seguir adiciona uma conexão, uma caixa de ferramentas e uma rede privada.

# 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 serviço de projeto provisiona ou se conecta a um projeto do Foundry e possui suas implantações de modelo.

deployments

Uma entrada de implantação também pode ser um arquivo externo: - $ref: ./deployments/embeddings.yaml.

rede

Defina network para provisionar uma conta protegida pela rede. O peSubnet campo é necessário e estabelece o ponto de extremidade privado da conta. Adicione agentSubnet para injetar o runtime do agente em sua própria sub-rede (traga sua própria rede virtual) ou omita-o para usar a rede gerenciada por Microsoft. Para obter um passo a passo completo, consulte a rede privada do agente hospedado.

Configuração de rede privada

Use network no azure.ai.project serviço para configurar o ponto de extremidade privado da conta e a saída do agente. O exemplo a seguir usa uma sub-rede gerenciada pelo cliente para o runtime 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 desabilita o acesso do plano de dados público para a conta. Não há suporte para um Registro de Contêiner do Azure criado automaticamente com essa configuração. Use a implantação do código-fonte ou especifique um predefinido image.

serviço azure.ai.agent

O serviço de agente carrega a definição do agente e suas configurações de build e implantação. É o serviço que substitui o antigo agent.yaml.

agentCard.skills e azure.ai.skill

agentCard.skills descreve as funcionalidades de um agente em seu cartão de descoberta. Ele fornece metadados para clientes e não cria ou anexa uma habilidade de Foundry reutilizável. Cada habilidade de cartão requer um id, namee description.

Um azure.ai.skill serviço cria uma habilidade com controle de versão com base em instruções e ferramentas permitidas opcionais. Declare-o separadamente em services; sua uses lista controla a ordem de dependência, mas não preenche agentCard.skills ou 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

Concluir um cartão de descoberta

Adicionar versione tagsexamples quando os clientes precisarem de metadados de descoberta mais avançados. Um cartão requer um e pelo menos uma description habilidade. Cada habilidade requer um id, namee 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 hospedado. Defina raiPolicyName como a ID de recurso do ARM completa da política:

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

O rai_policy tipo e raiPolicyName são necessários. A extensão aplica a primeira política válida na lista à configuração de IA responsável do agente hospedado. Para obter diretrizes de criação e gerenciamento de políticas, consulte Adicionar guardrails aos agentes hospedados.

Armazenamentos de memória

Use memoryStores para criar ou reutilizar repositórios de memória do Foundry antes da implantação. Cada repositório requer nomes de implantação de modelo de chat e de inserção existentes.

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

Os repositórios existentes não são atualizados durante a implantação. Se a definição declarada for diferente do repositório existente, azd relatará a diferença. Declarar um repositório de memória não altera o código do agente ou anexa automaticamente uma ferramenta de memória. Conecte seu aplicativo ao repositório de memória usando a ferramenta de pesquisa de memória ou as APIs do repositório de memória. Para obter detalhes, consulte Usar memória com agentes.

Configurar um ponto de extremidade do agente

Use agentEndpoint para configurar os protocolos e os esquemas de autorização publicados pelo ponto de extremidade do agente. Use um cartão de agente com um ponto de extremidade A2A para que outros agentes possam descobrir os recursos expostos.

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

Você também pode definir versionSelector.versionSelectionRules quando precisa controlar qual versão do agente recebe o tráfego de ponto de extremidade. O Serviço de Agente valida os valores de autorização e protocolo de ponto de extremidade durante a implantação.

protocols

protocols:
    - protocol: responses
      version: 2.0.0

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

Protocolos de runtime adicionais e pontos de extremidade de atividade

Além do suporte invocations_ws de invocationsresponsesagentes hospedados para invocações do WebSocket e a2aactivity para cenários de atividade do Microsoft 365 e do Teams.

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

Para um agente de atividade, adicione activity à configuração de ponto de extremidade público e use o esquema de autorização de Serviço de Bot necessário:

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

O protocolo atividade pode coexistir com outros protocolos no mesmo ponto de extremidade do agente. Para obter o comportamento do protocolo de runtime, consulte o que são agentes hospedados?.

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 de .azure/<env>/.env.

Ambiente, identidade e pontos de extremidade da plataforma

A plataforma reserva os prefixos e AGENT_ os FOUNDRY_ prefixos. Leia variáveis de plataforma, como FOUNDRY_PROJECT_ENDPOINT, no código do aplicativo, mas não as defina ou substitua em env. Os valores de ambiente definidos pelo agente são cadeias de caracteres.

Cada agente hospedado implantado recebe uma identidade de agente Microsoft Entra ID dedicada e um ponto de extremidade. Não adicione um identity bloco ao serviço do agente. A identidade do agente pode usar o ponto de extremidade do projeto e o armazenamento de sessão por padrão. Atribua as funções adicionais de identidade quando o agente precisar acessar recursos externos. Para obter detalhes, consulte a referência de permissões do agente hospedado.

Os protocolos que você declara determinam os pontos de extremidade que estão ativos após a implantação. Execute azd ai agent show para inspecionar o agente implantado e suas URLs de ponto de extremidade.

Após a implantação, azd grava os seguintes valores no ambiente ativo, usando o nome do serviço normalizado no lugar de <SERVICE>:

• AGENT_<SERVICE>_NAME
• AGENT_<SERVICE>_VERSION
• AGENT_<SERVICE>_ENDPOINT
• AGENT_<SERVICE>_<PROTOCOL>_ENDPOINT para habilitados responses, invocationse invocations_ws protocolos

Use a saída específica do protocolo quando seu aplicativo ou automação precisar de uma URL de invocação. O ponto de extremidade base identifica a versão do agente implantado para operações de gerenciamento de sessão.

contêiner

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

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

Implantação de código-fonte

Defina codeConfiguration para implantar o código-fonte como um ZIP em vez de uma imagem de contêiner. Especifique um nome de arquivo de ponto de entrada ou nome do assembly. azd combina-o com o runtime selecionado quando ele cria a versão do agente hospedado.

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

Use remote_build para restaurar dependências das fontes do projeto ou use bundled quando o ZIP contiver dependências compatíveis com Linux. Não combine com a codeConfiguration configuração de contêiner baseada em imagem. Para obter diretrizes de empacotamento e dependência, consulte Implantar um agente hospedado do código-fonte.

Compilações de contêiner e imagens predefinidas

Use um Dockerfile abaixo project para criar uma imagem de contêiner ou definir image para implantar uma imagem predefinida:

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

Quando um Dockerfile e um image estiverem disponíveis, escolha a imagem predefinida no prompt de implantação interativa. Para implantação autônoma, defina AZD_AGENT_SKIP_ACRtrue no ambiente ativo azd para selecionar a imagem configurada. Para obter permissões de registro e implantação de registro privado, consulte Implantar um agente hospedado com uma Registro de Contêiner do Azure privada.

Limitações de metadados e esquema

Use valores de cadeia de caracteres para metadados de agente implantados. O authors valor dos metadados pode ser uma lista de cadeias de caracteres. Não confie displayNameem , inputSchemaou outputSchema para configurar o agente hospedado implantado; a configuração unificada aceita esses campos, mas a solicitação de criação do agente hospedado não os usa.

serviço azure.ai.connection

Uma conexão vincula o projeto a um recurso externo. A chave de serviço é o nome da conexão e o serviço depende do projeto por meio 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 conexão se aplicam durante azd provision, não azd deploy. Armazene valores de credencial em seu azd ambiente e faça referência a eles ${VAR} em vez de colocar segredos.azure.yaml

serviço azure.ai.toolbox

Uma caixa de ferramentas é um pacote nomeado de ferramentas que os agentes fazem referência. As ferramentas com suporte de conexão nomeam um azure.ai.connection serviço por meio 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 faz referência a uma caixa de ferramentas adicionando o nome do serviço da caixa de ferramentas a ambos uses e à sua toolboxes lista.

Consumir um ponto de extremidade da caixa de ferramentas

Em um projeto de serviço dividido, uses controla a ordem de implantação. Seu aplicativo se conecta ao ponto de extremidade MCP da caixa de ferramentas em runtime. Passe o nome ou o ponto de extremidade da caixa de ferramentas para o aplicativo e env, em seguida, construa o ponto de extremidade do consumidor no código do FOUNDRY_PROJECT_ENDPOINT agente. Para obter um exemplo de ponta a ponta, consulte Usar uma caixa de ferramentas com um agente hospedado.

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

Um azure.ai.skill serviço define uma diretriz comportamental reutilizável que os agentes fazem referência por 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 usam por meio usesde . Para saber mais sobre como adicionar ferramentas para uso de agente, consulte o que é a Caixa de Ferramentas na Foundry? e use rotinas.

Habilidades e rotinas são recursos separados. Declarar um serviço controla seu ciclo de vida, mas não anexa automaticamente uma habilidade ao agente ou infere um destino de ação de rotina. Configure explicitamente o aplicativo de consumo ou a ação de rotina.

Dependências com usos

O uses campo declara os serviços dos quais um determinado serviço depende. azd usa esse grafo para ordenar o provisionamento e conectar referências, como conexões e caixas de ferramentas de um agente.

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

O arquivo inclui com $ref

Qualquer entrada de serviço ou lista pode ser substituída por uma referência a um arquivo YAML ou JSON externo. Caminhos relativos resolvidos do arquivo que contém o $ref. Não há suporte para URLs remotas.

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

O arquivo inclui permitir que você mantenha definições de agente grandes em seus próprios arquivos e compartilhe definições entre projetos.

Mantenha os campos de serviço principais na entrada raiz azure.yaml quando você usa um serviço $ref: host, , uses, project, , language, imagee docker. Coloque campos de definição de propriedade do provedor, como kind, name, descriptione protocols, no mapeamento referenciado. $ref resolve arquivos YAML ou JSON locais recursivamente; Não há suporte para URLs e ciclos de referência.

Substituição de variável

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

Modos de implantação e infraestrutura

sem Bicep por padrão

azd ai agent init é sem bicep por padrão: ele não grava um infra/ diretório e azd sintetiza a infraestrutura de seus azure.yaml serviços no momento da provisionamento. Para materializar arquivos de infraestrutura como código, ejete-os:

Quando infra estiver presente, azure.yamlazd use esses arquivos em vez de sintetizar a infraestrutura.

Modos de implantação

Um agente hospedado é implantado em um dos dois modos:

Para implantações de origem, o codeConfiguration campo no serviço do agente captura o runtime e o ponto de entrada. Para imagens predefinidas, defina o image campo no serviço do agente e ignore o build do Dockerfile.

Migração de configuração herdada

Definições de agente mais antigas podem aninhar variáveis de ambiente em config: env. No unificado azure.yaml, mova o env mapeamento para o serviço do 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 preenchimento automático do IDE:

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

Conteúdo relacionado

• Criar azure.yaml para agentes hospedados
• Inicializar um projeto de agente hospedado com a CLI do desenvolvedor do Azure
• Infraestrutura de agente hospedado com a CLI do desenvolvedor do Azure
• Contrato de runtime do agente hospedado
• O que são agentes hospedados?