Referencia del esquema agent.yaml

Importante

Los elementos marcados como versión preliminar en este artículo se encuentran actualmente en versión preliminar. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y Microsoft no lo recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

Nota:

Los manifiestos del agente (agent.manifest.yaml) y las definiciones de agente independientes (agent.yaml) están en desuso. A partir de las extensiones foundry azd (azure.ai.agents 1.0.0-beta.1), toda la configuración del agente hospedado reside en un único azure.yaml. Consulte Creación de azure.yaml para agentes hospedados y referencia de azure.yaml para agentes hospedados.

La especificación AgentSchema es un estándar abierto para definir agentes de IA. Al compilar agentes hospedados, se trabaja principalmente con tres tipos de esquema de nivel superior: AgentDefinition, AgentManifest y ContainerAgent. Este modelo de esquema heredado para AgentManifest, AgentDefinition, agent.manifest.yamly agent.yaml se conserva como referencia y se reemplaza por azure.yaml. El esquema no es específico de una herramienta. La CLI de Azure Developer (azd) y el kit de herramientas de Microsoft Foundry para Visual Studio Code ambos lo usan.

El esquema aparece en dos contextos de archivo con convenciones de nomenclatura distintas:

  • agent.manifest.yaml es un AgentManifest, una plantilla parametrizada que usan los ejemplos heredados. La inicialización actual azd ai agent init -t requiere un azure.yaml documento de proyecto y rechaza los contenedores AgentManifest.
  • agent.yaml es un AgentDefinition, la configuración concreta que la inicialización heredada escribió en el proyecto en src/<agent>/agent.yaml.

Ambos archivos describen lo que es un agente: su modelo, herramientas, protocolos, entorno y recursos. Esto es distinto de azure.yaml, que describe cómo aprovisionar e implementar Azure recursos. Para obtener la azure.yaml referencia, consulte referencia de azure.yaml para agentes hospedados.

Tipos de esquema

AgentDefinition

AgentDefinition es una especificación concreta de un agente que está listo para ejecutarse. Describe una instancia de agente única con una configuración específica y sin {{ parameter }} marcadores de posición de plantilla.

Cada AgentDefinition tiene un kind campo que determina el tipo de agente.

Kind Description
prompt Un agente basado en mensajes configurado solo mediante instrucciones.
hosted Un agente en contenedor implementado como una imagen de contenedor.
workflow Agente de orquestación que coordina otros agentes.

Un AgentDefinition generado todavía puede contener ${VAR_NAME} referencias. Estos son azd marcadores de posición de variables de entorno, no forman parte de la especificación AgentSchema. Permiten que un único archivo de definición funcione en varios azd entornos mediante la resolución de valores del archivo de .azure/<env>/.env cada entorno en tiempo de implementación.

AgentManifest

AgentManifest es una plantilla parametrizada para crear agentes dinámicamente. Encapsula un AgentDefinition como campo template y agrega:

  • parameters: valores que se solicitan o insertan en el momento de la creación mediante la {{ parameter }} sintaxis de sustitución.
  • resources: dependencias externas, como implementaciones de modelos, cuadros de herramientas o conexiones.

Use un AgentManifest cuando necesite plantillas reutilizables o quiera implementar agentes similares con configuraciones diferentes. Al ejecutar azd ai agent init, normalmente apunta a un manifiesto, ya sea seleccionando una plantilla o proporcionando una dirección URL. El proceso de inicialización solicita valores de parámetro y genera un AgentDefinition.

ContainerAgent

ContainerAgent es un AgentDefinition con kind: hosted. Extiende la definición base con campos específicos del contenedor y es el template dentro de un AgentManifest al compilar un agente hospedado.

Cuándo usar un manifiesto o una definición

Usar un manifiesto cuando Usar una definición cuando
Puede publicar una plantilla de agente reutilizable para que otros usuarios creen instancias. Implemente un agente específico de un solo propósito.
Quiere que los usuarios configuren el modelo, las herramientas o las conexiones en el momento de la inicialización. Todos los valores de configuración son conocidos y fijos.
Cree una plantilla de ejemplo o de inicio. Ya ejecutó azd ai agent init y ha generado una definición.

La mayoría de los desarrolladores comienzan desde un manifiesto hasta azd ai agent init y luego trabajan con la definición generada. Los autores de plantillas y los publicadores de ejemplo son los principales creadores de manifiestos.

Campos de nivel superior

La referencia siguiente documenta los campos de manifiesto, que son un superconjunto de los campos de definición.

Field Tipo Obligatorio Description
name string Sí Nombre del manifiesto del agente.
description string No Descripción del agente.
metadata object No Metadatos adicionales, como tags.
template ContainerAgent Sí Plantilla de definición del agente.
parameters object No Parámetros configurables que se solicitan durante la inicialización.
resources array Sí Recursos requeridos por el agente.

template (ContainerAgent)

El template campo define el agente de contenedor hospedado.

Field Tipo Obligatorio Description
name string Sí Nombre del agente.
kind string Sí Debe ser hosted para agentes hospedados.
protocols array Sí Compatibilidad con protocolos.
environment_variables array No Variables de entorno para el contenedor.
resources object No Recursos de CPU y memoria del contenedor.
image string No Ruta de acceso de imagen de contenedor precompilada.
dockerfilePath string No Ruta de acceso al Dockerfile.

protocolos

protocols:
  - protocol: responses    # OpenAI Responses API
    version: 2.0.0
Protocol Description
responses Api de respuestas de OpenAI. Incluye la administración del historial de conversaciones.
invocations Protocolo de carga personalizado. No hay administración de conversaciones integrada.

Para obtener la especificación de protocolo completa, consulte Contrato en tiempo de ejecución del agente hospedado.

environment_variables

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

La ${ } sintaxis hace referencia a azd variables de entorno de .azure/<env>/.env.

Nota:

No declare FOUNDRY_PROJECT_ENDPOINT en environment_variables. La plataforma lo inserta automáticamente en contenedores hospedados y azd ai agent run lo establece para el desarrollo local. Declararlo aquí es redundante y corre el riesgo de sombrear el valor de la plataforma.

parameters

Los parámetros se solicitan durante azd ai agent init. Use secret: true para valores confidenciales.

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

resources

Los recursos definen lo que necesita el agente. Las formas siguientes describen qué manifiestos declaran y qué azd ai agent init escriben en el proyecto. Después de init, administre los mismos recursos con ámbito de proyecto en tiempo de ejecución con comandos directos de la CLI: azd ai connection, azd ai toolbox, azd ai skilly azd ai routine.

Nota:

El esquema no incluye un campo de aptitudes. Los azd ai agent initcomandos , azd ai agent runy azd up no descargan automáticamente las aptitudes. Administre las aptitudes como recursos de nivel de proyecto con azd ai skill y conéctelos al entorno de ejecución del agente usted mismo.

Recurso de modelo

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

Recurso de conexión

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

Recurso del cuadro de herramientas

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 }}"

Una versión del cuadro de herramientas incluye tres tipos de entradas: entradas sin procesar tools (funcionalidades integradas como web-search o code-interpreter), connections (conexiones de proyecto como un servidor MCP de herramientas remotas o un índice de búsqueda) y skills (referencias a aptitudes de proyecto existentes). La tools ranura se declara delante en el manifiesto. Agregue conexiones y referencias de aptitud incrementalmente con azd ai toolbox connection add y azd ai toolbox skill add.

Ejemplo 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 }}"

Sustitución de variables

La sustitución se produce en dos capas: los parámetros de manifiesto se resuelven en tiempo de inicialización y las variables de entorno se resuelven en tiempo de ejecución o implementación. Después, un archivo de definición puede funcionar en todos los azd entornos.

Syntax Resuelto cuando Por qué
{{ param_name }} azd ai agent init Valores de parámetro de manifiesto que se le solicitaron al usuario.
${VAR_NAME} azd deploy o azd ai agent run azd variables de entorno de .azure/<env>/.env.

Contenido relacionado

  • Se actualizó por última vez el