Referência de esquema agent.yaml

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.

Note

Manifestos de agente (agent.manifest.yaml) e definições de agentes independentes (agent.yaml) estão obsoletos. A partir das extensões Foundry azd (azure.ai.agents 1.0.0-beta.1), toda a configuração de agentes alojados reside num único azure.yaml. Consulte Author azure.yaml para agentes hospedados e referência azure.yaml para agentes hospedados.

A especificação AgentSchema é um padrão aberto para definir agentes de IA. Quando constrói agentes alojados, trabalha principalmente com três tipos de esquema de topo: AgentDefinition, AgentManifest e ContainerAgent. Este modelo de esquema legado para AgentManifest, AgentDefinition, agent.manifest.yaml, e agent.yaml é mantido para referência e é substituído por azure.yaml. O esquema não é específico de uma ferramenta específica. O Azure Developer CLI (azd) e o Microsoft Foundry Toolkit para Visual Studio Code usam-no ambos.

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

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

Ambos os ficheiros descrevem o que é um agente: o seu modelo, ferramentas, protocolos, ambiente e recursos. Isto é distinto de azure.yaml, que descreve como provisionar e implementar recursos do Azure. Para referência azure.yaml , consulte a referência azure.yaml para agentes alojados.

Tipos de esquemas

Definição de Agente

Uma AgentDefinition é uma especificação concreta de um agente que está pronto a ser executado. Descreve uma única instância de agente com uma configuração específica e sem {{ parameter }} marcadores de template (marcadores de posição).

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

Variante	Description
`prompt`	Um agente baseado em prompts configurado apenas por instruções.
`hosted`	Um agente containerizado implementado como imagem de contentor.
`workflow`	Um agente de orquestração que coordena outros agentes.

Uma AgentDefinition gerada ainda pode conter ${VAR_NAME} referências. Estes são azd marcadores de variáveis de ambiente, não fazem parte da especificação AgentSchema. Permitem que um único ficheiro de definição funcione em múltiplos azd ambientes, resolvendo valores de cada .azure/<env>/.env ficheiro no momento da implementação.

AgentManifest

Um AgentManifest é um modelo parametrizado para criar agentes de forma dinâmica. Envolve um AgentDefinition como campo template e acrescenta:

parameters: valores que são solicitados ou injetados na altura da criação, usando {{ parameter }} sintaxe de substituição.
resources: dependências externas como implementações de modelos, caixas de ferramentas ou ligações.

Use um AgentManifest quando precisar de templates reutilizáveis ou quiser implementar agentes semelhantes com configurações diferentes. Quando executa azd ai agent init, normalmente aponta para um manifesto, seja selecionando um modelo ou fornecendo um URL. O processo init solicita valores de parâmetros e gera uma AgentDefinition.

ContainerAgent

Um AgentContainer é um AgentDefinition com kind: hosted. Estende a definição base com campos específicos do contentor e está template dentro de um AgentManifest quando se constrói um agente alojado.

Quando usar um manifesto ou uma definição

Use um manifesto quando	Use uma definição quando
Publicas um modelo de agente reutilizável para outros instanciarem.	Utiliza-se um agente específico e de propósito único.
Quer que os utilizadores configurem o modelo, as ferramentas ou as ligações no momento inicial.	Todos os valores de configuração são conhecidos e fixos.
Constróis um modelo de exemplo ou de iniciação.	Já correu `azd ai agent init` e tem uma definição gerada.

A maioria dos programadores começa a partir de um manifesto e azd ai agent init depois trabalha com a definição gerada. Os autores de modelos e os editores de exemplos são os principais criadores dos manifestos.

Campos de nível superior

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

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

template (ContainerAgent)

O template campo define o agente contentor hospedado.

Field	Tipo	Required	Description
`name`	cadeia (de caracteres)	Yes	Nome do agente.
`kind`	cadeia (de caracteres)	Yes	Deve ser `hosted` para agentes alojados.
`protocols`	matriz	Yes	Suporte a protocolos.
`environment_variables`	matriz	No	Variáveis de ambiente para o contentor.
`resources`	objecto	No	Recursos de CPU e memória do contentor.
`image`	cadeia (de caracteres)	No	Caminho da imagem do contentor pré-construído.
`dockerfilePath`	cadeia (de caracteres)	No	Caminho para o Dockerfile.

protocolos

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

Protocolo	Description
`responses`	API de Respostas OpenAI. Inclui gestão do histórico de conversas.
`invocations`	Protocolo personalizado de carga útil. Sem gestão de conversas incorporada.

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

environment_variables

Para agentes Python, configure PYTHONNOUSERSITE como "1" antes do arranque do interpretador. Para novas implementações, utilize a configuração atual azure.yaml descrita em Configurar Python de arranque. Os exemplos legados abaixo mostram o cenário equivalente.

environment_variables:
  - name: FOUNDRY_MODEL_NAME
    value: ${FOUNDRY_MODEL_NAME}
  - name: PYTHONNOUSERSITE
    value: "1"

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

Note

Não declare FOUNDRY_PROJECT_ENDPOINT em environment_variables. A plataforma injeta-o automaticamente em contentores alojados e azd ai agent run configura-o para desenvolvimento local. Declará-lo aqui é redundante e corre o risco de prejudicar o valor da plataforma.

parameters

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

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

resources

Os recursos definem o que o agente precisa. As formas abaixo descrevem o que manifestos declaram e o que azd ai agent init se escreve no seu projeto. Após o init, gere os mesmos recursos com âmbito de projeto em tempo de execução com comandos diretos de CLI: azd ai connection, azd ai toolbox, azd ai skill, e azd ai routine.

Note

O esquema não inclui um campo de competências. Os azd ai agent initcomandos , azd ai agent run, e azd up não descarregam automaticamente as habilidades. Gere competências como recursos azd ai skill ao nível do projeto e integra-as tu próprio no tempo de execução do teu agente.

Recurso do modelo

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

Recurso de ligação

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

Recurso da 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 toolbox transporta três tipos de entradas: entradas brutas tools (capacidades incorporadas como web-search ou code-interpreter), connections (ligações a projetos como um servidor MCP remota ou um índice de pesquisa) e skills (referências a competências existentes do projeto). A tools vaga está declarada logo à frente no manifesto. Adicione ligações e referências de competências 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: PYTHONNOUSERSITE
      value: "1"
    - 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áveis

A substituição ocorre em duas camadas: os parâmetros de manifestação resolvem-se no tempo de iniciação, e as variáveis do ambiente resolvem-se no momento de execução ou implementação. Um ficheiro de definição pode então funcionar em todos os teus azd ambientes.

Sintaxe	Resolvido quando	Por quê
`{{ param_name }}`	`azd ai agent init`	Valores de parâmetros de manifestar solicitados pelo utilizador.
`${VAR_NAME}`	`azd deploy` ou `azd ai agent run`	`azd` variáveis de ambiente a partir de `.azure/<env>/.env`.

Comentários

Esta página foi útil?

Última atualização a 2026-07-07

Referência de esquema agent.yaml

Tipos de esquemas

Definição de Agente

AgentManifest

ContainerAgent

Quando usar um manifesto ou uma definição

Campos de nível superior

template (ContainerAgent)

protocolos

environment_variables

parameters

resources

Recurso do modelo

Recurso de ligação

Recurso da Caixa de Ferramentas

Exemplo completo

Substituição de variáveis

Conteúdo relacionado

Comentários

Recursos adicionais