Referência de esquema agent.yaml

Importante

Os itens marcados como visualização neste artigo estão atualmente em versão prévia. Essa visualização é fornecida sem um contrato de nível de serviço e Microsoft não recomenda isso 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.

Note

Manifestos do agente (agent.manifest.yaml) e definições de agente autônomo (agent.yaml) são preteridos. A partir das extensões do Foundry azd (azure.ai.agents 1.0.0-beta.1), toda a configuração do agente hospedado reside em um único azure.yaml. Consulte Author azure.yaml para obter agentes hospedados e referência azure.yaml para agentes hospedados.

A especificação AgentSchema é um padrão aberto para definir agentes de IA. Ao criar agentes hospedados, você trabalha principalmente com três tipos de esquema de nível superior: AgentDefinition, AgentManifest e ContainerAgent. Esse modelo de esquema herdado paraAgentManifest, , AgentDefinitionagent.manifest.yamle agent.yaml é mantido para referência e é substituído por azure.yaml. O esquema não é específico para uma ferramenta. A CLI do Desenvolvedor Azure (azd) e o Microsoft Foundry Toolkit para Visual Studio Code usá-lo.

O esquema aparece em dois contextos de arquivo com convenções de nomenclatura distintas:

agent.manifest.yaml é um AgentManifest, um modelo parametrizado usado por exemplos herdados. A inicialização atual azd ai agent init -t requer um azure.yaml documento de projeto e rejeita wrappers AgentManifest.
agent.yaml é um AgentDefinition, a configuração concreta que a inicialização herdada escreveu em seu projeto em src/<agent>/agent.yaml.

Ambos os arquivos descrevem o que é um agente: seu modelo, ferramentas, protocolos, ambiente e recursos. Isso é diferente de azure.yaml, que descreve como provisionar e implantar recursos Azure. Para obter a azure.yaml referência, consulte a referência azure.yaml para agentes hospedados.

Tipos de esquema

AgentDefinition

Um AgentDefinition é uma especificação concreta de um agente que está pronto para ser executado. Ele descreve uma única instância de agente com uma configuração específica e sem {{ parameter }} espaços reservados de modelo.

Cada AgentDefinition tem um kind campo que determina o tipo de agente.

Variante	Description
`prompt`	Um agente baseado em prompt configurado apenas por meio de instruções.
`hosted`	Um agente em contêineres implantado como uma imagem de contêiner.
`workflow`	Um agente de orquestração que coordena outros agentes.

Um AgentDefinition gerado ainda pode conter ${VAR_NAME} referências. Esses são azd espaços reservados de variável de ambiente, não fazem parte da especificação AgentSchema. Eles permitem que um único arquivo de definição funcione em vários azd ambientes resolvendo valores do arquivo de cada ambiente no momento da .azure/<env>/.env implantação.

AgentManifest

Um AgentManifest é um modelo parametrizado para criar agentes dinamicamente. Ele encapsula um AgentDefinition como seu template campo e adiciona:

parameters: valores que são solicitados ou injetados no momento da criação, usando {{ parameter }} a sintaxe de substituição.
resources: dependências externas, como implantações de modelo, caixas de ferramentas ou conexões.

Use um AgentManifest quando precisar de modelos reutilizáveis ou quiser implantar agentes semelhantes com configurações diferentes. Ao executar azd ai agent init, você normalmente aponta para um manifesto, selecionando um modelo ou fornecendo uma URL. O processo de inicialização solicita valores de parâmetro e gera um AgentDefinition.

ContainerAgent

Um ContainerAgent é um AgentDefinition com kind: hosted. Ele estende a definição base com campos específicos do contêiner e é o template interior de um AgentManifest quando você cria um agente hospedado.

Quando usar um manifesto ou uma definição

Usar um manifesto quando	Usar uma definição quando
Você publica um modelo de agente reutilizável para outras pessoas criarem uma instância.	Você implanta um agente específico de uso único.
Você deseja que os usuários configurem o modelo, as ferramentas ou as conexões no momento da inicialização.	Todos os valores de configuração são conhecidos e corrigidos.
Você cria um modelo de exemplo ou de início.	Você já executou `azd ai agent init` e tem uma definição gerada.

A maioria dos desenvolvedores começa de um manifesto e azd ai agent init , em seguida, trabalha com a definição gerada. Autores de modelos e editores de exemplo são os principais criadores de manifestos.

Campos de nível superior

A referência abaixo documenta os campos de manifesto, que são um superconjunto dos campos de definição.

Field	Tipo	Obrigatório	Description
`name`	cadeia	Yes	Nome do manifesto do agente.
`description`	cadeia	No	Descrição do agente.
`metadata`	objeto	No	Metadados adicionais, como `tags`.
`template`	ContainerAgent	Yes	O modelo de definição do agente.
`parameters`	objeto	No	Parâmetros configuráveis solicitados durante o init.
`resources`	matriz	Yes	Recursos exigidos pelo agente.

template (ContainerAgent)

O template campo define o agente de contêiner hospedado.

Field	Tipo	Obrigatório	Description
`name`	cadeia	Yes	Nome do agente.
`kind`	cadeia	Yes	Deve ser `hosted` para agentes hospedados.
`protocols`	matriz	Yes	Suporte ao protocolo.
`environment_variables`	matriz	No	Variáveis de ambiente para o contêiner.
`resources`	objeto	No	Recursos de CPU e memória do contêiner.
`image`	cadeia	No	Caminho de imagem de contêiner predefinido.
`dockerfilePath`	cadeia	No	Caminho para o Dockerfile.

Protocolos

protocols:
  - protocol: responses    # OpenAI Responses API
    version: 2.0.0

Protocol	Description
`responses`	API de respostas OpenAI. Inclui o gerenciamento de histórico de conversas.
`invocations`	Protocolo de conteúdo personalizado. Nenhum gerenciamento de conversa interno.

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

environment_variables

environment_variables:
  - name: FOUNDRY_MODEL_NAME
    value: ${FOUNDRY_MODEL_NAME}

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

Note

Não declare FOUNDRY_PROJECT_ENDPOINT em environment_variables. A plataforma injeta-a automaticamente em contêineres hospedados e azd ai agent run a define para desenvolvimento local. Declarar aqui é redundante e corre o risco de sombrear o valor da plataforma.

parameters

Os parâmetros são solicitados durante azd ai agent init. Use secret: true para valores confidenciais.

parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token

resources

Os recursos definem o que o agente precisa. As formas abaixo descrevem quais manifestos declaram e o que azd ai agent init grava em seu projeto. Após a inicialização, gerencie os mesmos recursos com escopo de projeto em runtime com comandos diretos da CLI: azd ai connection, , azd ai toolboxe azd ai skillazd ai routine.

Note

O esquema não inclui um campo de habilidades. Os azd ai agent initcomandos e azd ai agent run os azd upcomandos não baixam automaticamente as habilidades. Gerencie habilidades como recursos azd ai skill no nível do projeto e conecte-as ao runtime do agente por conta própria.

Recurso de modelo

resources:
  - kind: model
    name: chat
    id: gpt-4.1-mini

Recurso de conexão

resources:
  - kind: connection
    name: MyConnection
    target: https://api.example.com
    category: remoteTool
    credentials:
        type: CustomKeys
        keys:
            Authorization: "Bearer {{ my_api_key }}"

Recurso de caixa de ferramentas

resources:
  - kind: toolbox
    name: agent-tools
    description: Agent toolbox
    tools:
      - name: webSearch
        type: builtin
        capability: web-search
      - name: codeInterpreter
        type: builtin
        capability: code-interpreter
      - name: myMcp
        type: connection
        connection: "{{ MyConnection }}"

Uma versão da caixa de ferramentas contém três tipos de entradas: entradas brutas tools (recursos internos como web-search ou code-interpreter), connections (conexões de projeto como um servidor MCP de ferramenta remota ou um índice de pesquisa) e skills (referências a habilidades de projeto existentes). O tools slot é declarado antecipadamente no manifesto. Adicionar conexões e referências de habilidades incrementalmente com azd ai toolbox connection add e azd ai toolbox skill add.

Exemplo completo

name: my-web-search-agent
description: An agent with web search and MCP tools

metadata:
  tags:
    - AI Agent Hosting

template:
  name: my-web-search-agent
  kind: hosted
  protocols:
    - protocol: responses
      version: 2.0.0
  environment_variables:
    - name: FOUNDRY_MODEL_NAME
      value: ${FOUNDRY_MODEL_NAME}
    - name: TOOLBOX_ENDPOINT
      value: ${TOOLBOX_ENDPOINT}

parameters:
  github_pat:
    secret: true
    description: GitHub PAT for MCP connection

resources:
  - kind: model
    name: chat
    id: gpt-4.1-mini

  - kind: connection
    name: GithubMcpConnection
    target: https://api.githubcopilot.com/mcp
    category: remoteTool
    credentials:
        type: CustomKeys
        keys:
            Authorization: "Bearer {{ github_pat }}"

  - kind: toolbox
    name: agent-tools
    description: Web search and GitHub MCP tools
    tools:
      - name: webSearch
        type: builtin
        capability: web-search
      - name: github
        type: connection
        connection: "{{ GithubMcpConnection }}"

Substituição de variável

A substituição ocorre em duas camadas: os parâmetros de manifesto são resolvidos no momento da inicialização e as variáveis de ambiente são resolvidas em tempo de execução ou implantação. Um arquivo de definição pode funcionar em todos os seus azd ambientes.

Sintaxe	Resolvido quando	Pelo que
`{{ param_name }}`	`azd ai agent init`	Valores de parâmetro de manifesto solicitados pelo usuário.
`${VAR_NAME}`	`azd deploy` ou `azd ai agent run`	`azd` variáveis de ambiente de `.azure/<env>/.env`.

Comentários

Esta página foi útil?

Última atualização em 2026-10-16

Referência de esquema agent.yaml

Tipos de esquema

AgentDefinition

AgentManifest

ContainerAgent

Quando usar um manifesto ou uma definição

Campos de nível superior

template (ContainerAgent)

Protocolos

environment_variables

parameters

resources

Recurso de modelo

Recurso de conexão

Recurso de caixa de ferramentas

Exemplo completo

Substituição de variável

Conteúdo relacionado

Comentários

Recursos adicionais