Importar un agente declarativo de Microsoft Agent Framework
Este recorrido guiado importa un agente declarativo de Microsoft Agent Framework — un asistente que responde preguntas a partir de la documentación que busca a través de un servidor MCP — y compila la aplicación para Docker Compose. La importación redacta cada archivo que lee la compilación: el agente y su modelo, la clave que el agente presenta al modelo como referencia a una variable, y las realizaciones de cada uno. Pregunta una sola vez por el único valor que ningún agente declarativo contiene, la imagen en la que se ejecuta tu aplicación. Cada archivo y cada bloque de salida de abajo proceden de una ejecución real; el agente declarativo y cada etapa del recorrido están en el ejemplo import-agent-framework, donde un script de comprobación vuelve a ejecutar la importación, compara lo que escribe, lo que imprime y los bloques que cita esta página con los archivos que se guardan allí, y valida y compila lo que escribió la importación.
Generar el ejemplo
Puedes ejecutar esta importación con los comandos de esta página o pedir a tu asistente de IA que la ejecute por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example import-agent-frameworkDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva; el siguiente, más abajo, entra en la carpeta source de la carpeta nueva, que contiene lo que esta página importa y es donde se ejecuta la importación:
cd import-agent-framework
El proyecto
Una aplicación creada sobre Agent Framework puede cargar un agente desde un agente declarativo: un documento YAML de tipo Prompt que nombra el modelo del agente, sus instrucciones y sus herramientas. Este, escrito para este recorrido, nombra gpt-4.1-mini de OpenAI y el servidor MCP que publica Microsoft Learn:
kind: Promptname: SupportAgentdisplayName: Support Assistantdescription: Answers a customer's question about the product from its documentation.instructions: You answer customers' questions about the product, from its documentation only.model: id: gpt-4.1-mini provider: OpenAI apiType: Responses options: temperature: 0.2 connection: kind: key key: =Env.OPENAI_API_KEYtools: - kind: mcp name: microsoft_learn description: Search Microsoft's documentation on Microsoft Learn. url: https://learn.microsoft.com/api/mcp approvalMode: kind: never allowedTools: - microsoft_docs_search - microsoft_docs_fetchLa clave del modelo se escribe como =Env.OPENAI_API_KEY, así que el archivo no contiene ninguna clave. Agent Framework lee esa expresión de la variable de entorno OPENAI_API_KEY solo donde la aplicación carga el agente declarativo con AgentFactory(safe_mode=False), el ajuste de seguridad propio de Agent Framework, y hay un runtime de .NET presente; de lo contrario, la clave es el texto de la expresión tal como está escrito. El código de la aplicación, que carga el agente declarativo, nunca lo lee la importación y no forma parte del ejemplo. Junto al archivo, un .aggrega-config.yaml convierte la carpeta en un espacio de trabajo:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside support-agent.yaml.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.aiLa importación hace referencia a los Components del catálogo para el agente de Agent Framework y el modelo de OpenAI, y --target genera un Manifest a partir de sus Recipes. El espacio de trabajo no nombra ninguna carpeta de catálogo, así que la importación lee el catálogo de la biblioteca estándar del registro del que obtiene su importador: una instantánea firmada del catálogo publicado, que la primera importación obtiene, verifica y guarda en la caché de contenido del espacio de trabajo, y que se nombra por su digest en el archivo de registro que la importación escribe junto a sus borradores. Un espacio de trabajo que nombra sus propias carpetas de catálogo — en AGGREGA_CATALOG_DIRS o bajo workspace.catalog_dirs — importa frente a ellas en su lugar.
Qué pide la importación
Un agente declarativo nombra su modelo, nunca la imagen en la que se ejecuta la aplicación: esa imagen la construyes a partir de tu proyecto. El catálogo no tiene ninguna imagen predeterminada para una aplicación creada sobre Agent Framework, así que la importación la pide. Ejecutada en una terminal sin una respuesta a mano, pregunta:
The drafts leave values empty that the source cannot hold. Answer each one, or press Enter to leave it for later in the answers file:
release.yaml spec.components.supportagent.infra.image Container image running the application built on Microsoft Agent Framework.>y escribe la respuesta en los borradores y en import-answers.yaml, junto a support-agent.yaml, de modo que la siguiente importación la lee de ahí y no pregunta nada. Sin terminal — en integración continua o a través de una tubería — no pregunta nada: escribe el archivo con la clave vacía y se detiene, nombrando el archivo. El ejemplo ya contiene el archivo, con la imagen respondida, ghcr.io/example/support-agent:1.0.0, que representa la imagen que construyes:
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # Container image running the application built on Microsoft Agent Framework. spec.components.supportagent.infra.image: "ghcr.io/example/support-agent:1.0.0" # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.supportagent.uses.model.gpt-4-1-mini.features.credential.infra.origin: "openai-api-key"La segunda respuesta es para una compilación para Kubernetes, con --target helm: allí el agente lee la clave de OpenAI de un Secret de Kubernetes, y la respuesta es el nombre del Secret, openai-api-key, nunca la clave. Una compilación para Docker Compose lee en cambio la clave de tu shell, así que esta importación no usa esa respuesta. El archivo de respuestas de la importación describe el archivo, las preguntas y las reglas para la respuesta a un secreto.
aggrega import enumera cada opción que admite el comando, entre ellas --answers, que nombra un archivo de respuestas guardado en otro lugar.
Entra en source:
cd sourceEjecutar la importación
Indica el archivo del agente declarativo. La importación lee cada agente declarativo como un archivo independiente y nunca como un directorio:
aggrega import support-agent.yaml --target composeEn la salida estándar enumera lo que escribió:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonEn la salida de error estándar, donde <workspace> representa la carpeta en la que la ejecutaste:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the agent-framework format, with drafted paths relative to <workspace>warn: the value of tools.microsoft_learn.url of node SupportAgent is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptyinfo: the answers file <workspace>/import-answers.yaml also answers spec.components.supportagent.uses.model.gpt-4-1-mini.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not appliedmapped SupportAgent (agent) to core/ai-agent/agent-framework as a reference, NONEmapped gpt-4.1-mini (model) to core/ai-model/openai as a reference, NONEmade no choice for SupportAgent#microsoft_learn (tool)Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)
- La línea
warnnombra un valor que puede contener una clave — la dirección de un servidor MCP — y dice que se lleva tal como está escrito. Esta dirección no contiene ninguna. - La línea
infonombra la respuesta que los borradores de Docker Compose no usan, guardada en el archivo de respuestas para una compilación para Kubernetes. - Las líneas
mappeddicen que el agente es una instancia del agente de Agent Framework de la biblioteca estándar,core/ai-agent/agent-framework, y su modelo una instancia decore/ai-model/openai. Su nivel indicaNONE: la importación de Agent Framework hace referencia a estos Components por lo que nombra el agente declarativo, en lugar de comparar cada uno con el catálogo. - La línea
made no choicees el servidor MCP, para el que la importación no genera ningún Component, por el motivo que dan los comentarios deaggregate.yaml. - La línea
Pull completees la importación obteniendo aquello de lo que depende la Release redactada, como haceaggrega pull, enrelease.lock, para que los borradores se validen y se compilen de inmediato. Con--offline, la importación no obtiene nada e indica el comandoaggrega pullque hay que ejecutar.
Lo que escribe
El Aggregate, la Release y el Manifest se llaman imported/supportagent, por el name del agente, SupportAgent, reducido a supportagent — su displayName no se lee — bajo el namespace que fija el ajuste target_namespace del importador, imported salvo que fijes otro (Ajustes).
aggregate.yaml — el agente, cableado a su modelo con la clave que presenta declarada en la conexión, y el modelo:
# Not read: the application's code, which loads each declarative agent and binds the functions of its function tools; the application runs in the image the Release names for each instance, and loads its declarative agents itself.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/supportagent version: 0.1.0 description: Draft Aggregate imported from a source in the agent-framework format.spec: components: # The declarative agent SupportAgent. # Read by the application from the declarative agent, and taken by no key of core/ai-agent/agent-framework: instructions, the options of its model requests (temperature). # The MCP server microsoft_learn, drafted as no Component and no connection, since Agent Framework sends it to the model's provider as a hosted tool, and the provider, not the application, reaches it at its url, which must therefore be reachable from the provider; its url is written above supportagent's entry in the Release. # Stated by the declarative agent for microsoft_learn: its description, "Search Microsoft's documentation on Microsoft Learn."; its approval mode, never; the tools of the server it allows, microsoft_docs_search, microsoft_docs_fetch. supportagent: type: core/ai-agent/agent-framework values: display_name: "Support Assistant" description: "Answers a customer's question about the product from its documentation." uses: model: gpt-4-1-mini: target: gpt-4-1-mini # For the compose target, the lines below declare credential on gpt-4-1-mini: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. features: credential: type: core/secret-value values: key: OPENAI_API_KEY # The model gpt-4.1-mini, which SupportAgent names with the OpenAI provider. gpt-4-1-mini: type: core/ai-model/openai values: model: "gpt-4.1-mini"El servidor MCP no es un Component ni una conexión del agente: Agent Framework lo envía al proveedor del modelo como herramienta alojada, y es el proveedor, no la aplicación, quien lo alcanza en su url, que por tanto debe ser accesible desde el proveedor. Las instrucciones, las opciones de las solicitudes al modelo y la descripción, el modo de aprobación y las herramientas permitidas del servidor permanecen en el agente declarativo, que lee la aplicación; los comentarios nombran cada uno. La API de OpenAI es un servicio alojado, por lo que el Component del agente rechaza una conexión a ella que no lleve ninguna credencial; la conexión declara una, bajo la clave OPENAI_API_KEY, la variable de la que el agente declarativo lee su clave.
release.yaml — el entorno, la imagen, el puerto publicado y de dónde procede la clave:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/supportagent # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the agent-framework format.spec: aggregate: imported/supportagent manifest: imported/supportagent components: # The declarative agent also states these values for its model and its MCP servers, written here for review: # - model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads from the environment variable OPENAI_API_KEY only where the application loads the declarative agent with AgentFactory(safe_mode=False), Agent Framework's own security setting, and a .NET runtime is present; otherwise the value is the expression's text as written # - tools.microsoft_learn.url: "https://learn.microsoft.com/api/mcp" supportagent: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on Agent Framework, holding its declarative agent image: "ghcr.io/example/support-agent:1.0.0" # Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal. published_port: 8000 uses: model: gpt-4-1-mini: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential supportagent presents to gpt-4-1-mini on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" gpt-4-1-mini: {}El entorno, development, es un valor predeterminado que escribe la importación porque ningún agente declarativo nombra uno; cámbialo si la Release se despliega en otro lugar. La imagen es la respuesta que la importación leyó de import-answers.yaml. El agente se publica en la dirección de loopback de tu máquina, en el puerto 8000, y reenvía al puerto en el que escucha su programa, infra.port, 8000 salvo que lo definas. La clave es la referencia a la variable ${OPENAI_API_KEY}, nombrada según la variable que lee el agente declarativo, nunca un valor. La dirección del servidor MCP se escribe tal como la indica el agente declarativo, para su revisión, y no se define en ningún otro lugar: Agent Framework se la entrega al proveedor en su solicitud al modelo.
manifest.yaml — la Recipe de Compose del agente y del modelo, y la realización que escribe la referencia a la variable de la clave en el archivo Compose tal como está escrita:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/supportagent version: 0.1.0spec: mappings: components: type: core/ai-agent/agent-framework: compose/agent-framework core/ai-model/openai: compose/openai features: type: core/secret-value: compose/dotenv-secretrelease.lock registra, por digest, las entidades del catálogo a las que se resolvió la Release, y .aggrega-import.json es el registro de lo que escribió la importación, que lee un aggrega import --sync posterior.
Validar y compilar
aggrega validate --release release.yamlaggrega build --release release.yaml

La validación imprime:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)y la compilación, donde <workspace> representa la carpeta en la que la ejecutaste:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 1 file written to <workspace>/distLa línea notice es informativa: la Feature de secreto acepta su origin desde los values del Aggregate o desde la infra de la Release, y el aviso informa de que una hoja está declarada en ambos. No cambia ningún veredicto.
El servicio del agente en dist/compose/docker-compose.yaml:
services: supportagent: image: ghcr.io/example/support-agent:1.0.0 environment: OPENAI_BASE_URL: https://api.openai.com/v1 OPENAI_MODEL: gpt-4.1-mini OPENAI_API_KEY: ${OPENAI_API_KEY} ports: - 127.0.0.1:8000:8000 [… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version] networks: - composeLa aplicación recibe la dirección del modelo, su nombre y su clave en las variables que leen los clientes de OpenAI de Agent Framework, así que el =Env.OPENAI_API_KEY del agente declarativo lee la clave que adjuntó la Release allí donde la aplicación carga el agente como describe El proyecto. Ninguna variable lleva la dirección del servidor MCP, al que accede el proveedor. El modelo no obtiene un servicio propio: el agente accede a la API de OpenAI en su propia dirección. La clave es una referencia a una variable, que se rellena desde tu shell cuando se inicia el stack. El servicio publica su puerto solo en 127.0.0.1.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pega en él este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del Workspace aún no contiene una carpeta `import-agent-framework`, llama una vez a la herramienta `scaffold` con `example` establecido en `import-agent-framework` y sin `dir`: escribe el ejemplo en una nueva carpeta `import-agent-framework`, cuya carpeta `source` contiene lo que importa esta página. Después llama a la herramienta `import` con `workspace_root` establecido en `import-agent-framework/source`, `source` establecido en `support-agent.yaml` y `target` establecido en `compose`: lee las respuestas que necesita de `import-answers.yaml`, junto a `support-agent.yaml`, escribe sus borradores en `import-agent-framework/source` y descarga lo que estos necesitan. Después llama a la herramienta `validate` con `workspace_root` establecido en `import-agent-framework/source` y `release` establecido en `release.yaml`, y a la herramienta `build` con `workspace_root` establecido en `import-agent-framework/source`, `release` establecido en `release.yaml` y `write` establecido en true. Dime qué archivos escribió la compilación; están en `import-agent-framework/source/dist/`.Ábrelo en VS Code
Con la extensión de Aggrega para Visual Studio Code instalada, abre en VS Code la carpeta import-agent-framework/source, donde la importación escribió sus borradores. La carpeta contiene una sola Release, el release.yaml en borrador, así que el editor la selecciona por ti y comprueba los borradores con respecto a esa Release mientras los editas, marcando lo que encuentra en el archivo y en el panel Problemas. Aggrega: Show topology graph, en la paleta de comandos, dibuja los componentes de la Release y las conexiones entre ellos. Aggrega: Build, Aggrega: Preview build y Aggrega: Pull actúan sobre la misma Release, y cada uno es también un botón del panel Commands de la vista Aggrega en la barra de actividades; Build escribe sus archivos en el dist/ de la carpeta. Usar Aggrega en Visual Studio Code cubre el resto.
Ejecución
Tú construyes la imagen a partir del proyecto, con un Dockerfile propio: el código de la aplicación, con Agent Framework instalado y el agente declarativo dentro. Docker Compose ejecuta el comando propio de la imagen como servicio del agente, ya que la Recipe no define ninguno, así que ese comando debe seguir ejecutándose, y debe atender solicitudes si quieres llegar al agente. Tu programa decide la dirección, la ruta y la respuesta.
La ejecución de abajo usó una imagen así: Python con los paquetes agent-framework-core, agent-framework-openai y agent-framework-declarative de Agent Framework, un runtime de .NET — la imagen definía DOTNET_ROOT con su directorio y DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 — support-agent.yaml y, como comando de la imagen, un pequeño servidor HTTP propio del programa en el puerto 8000. El servidor carga el agente declarativo con AgentFactory(safe_mode=False), de modo que su =Env.OPENAI_API_KEY lee la clave que entrega la compilación, y ejecuta el agente una vez por cada POST /ask. Construye tu imagen en la raíz del proyecto, escribe su nombre en lugar de ghcr.io/example/support-agent:1.0.0 en import-answers.yaml y vuelve a importar con --sync, que escribe la nueva respuesta en los borradores y vuelve a hacer el pull; después, compila:
docker build -t docs-assistant:local .aggrega import support-agent.yaml --syncaggrega build --release release.yamlCon docs-assistant:local como respuesta, la sincronización nombra el único valor que cambió, entre las líneas que imprime:
changed spec.components.supportagent.infra.image in release.yamlDespués establece la clave en tu shell e inicia el stack:
export OPENAI_API_KEY='your OpenAI key'docker compose -p docs-assistant -f dist/compose/docker-compose.yaml up -d --wait-p da nombre al proyecto, como explica el paso de ejecución de Cómo se ejecuta una importación.
Probarlo
La solicitud siguiente llega al programa que ejecuta la imagen de esta guía: el agente declarativo detrás de un pequeño servidor HTTP en el puerto 8000, que responde a POST /ask. Tu propio programa decide su propia ruta y respuesta. Envíala a http://127.0.0.1:8000, la dirección que publica published_port, cuando el programa esté escuchando, unos segundos después de que se inicie el stack:
curl -sS -X POST http://127.0.0.1:8000/ask -H 'Content-Type: application/json' \ -d '{"question": "In one short sentence: what is Azure Container Apps?"}'{"error": "the agent failed: ChatClientException: (\"<class 'agent_framework_openai._chat_client.OpenAIChatClient'> service failed to complete the prompt: Error code: 401 - Incorrect API key provided: sk-place************-key. [… omitted: where to find an API key, and the same error repeated as the exception it wraps]"}La ejecución estableció OPENAI_API_KEY en un valor de marcador, así que la respuesta es el rechazo de OpenAI, transmitido por el programa. La clave que OpenAI rechazó es ese valor de marcador, mostrado enmascarado, así que el =Env.OPENAI_API_KEY del agente declarativo la leyó del entorno que entrega la compilación.
Detén el stack con:
docker compose -p docs-assistant -f dist/compose/docker-compose.yaml downEn Kubernetes, importa con --target helm y sube la imagen a un registro del que tu clúster descargue imágenes, indicándola en import-answers.yaml. Después crea el Secret openai-api-key y aplica la compilación, como describe el paso de ejecución de Cómo se ejecuta una importación. El Deployment del agente no tiene ningún Service, así que reenvía un puerto local hacia él. El comando se ejecuta hasta que lo detengas:
kubectl port-forward deploy/supportagent 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000Desde otra terminal, envía la misma solicitud al puerto reenviado:
curl -sS -X POST http://127.0.0.1:8000/ask -H 'Content-Type: application/json' \ -d '{"question": "In one short sentence: what is Azure Container Apps?"}'{"error": "the agent failed: ChatClientException: (\"<class 'agent_framework_openai._chat_client.OpenAIChatClient'> service failed to complete the prompt: Error code: 401 - Incorrect API key provided: sk-place************-key. [… omitted: where to find an API key, and the same error repeated as the exception it wraps]"}