Importar um agente declarativo do Microsoft Agent Framework
Este guia passo a passo importa um agente declarativo do Microsoft Agent Framework — um assistente que responde a perguntas a partir da documentação que pesquisa através de um servidor MCP — e compila a aplicação para Docker Compose. A importação rascunha todos os ficheiros que a compilação lê: o agente e o seu modelo, a chave que o agente apresenta ao modelo como referência a uma variável, e as realizações de cada um. Pergunta uma única vez pelo único valor que nenhum agente declarativo contém, a imagem em que a aplicação é executada. Todos os ficheiros e todos os blocos de saída abaixo provêm de uma execução real; o agente declarativo e cada etapa do guia estão no exemplo import-agent-framework, onde um script de verificação volta a executar a importação, compara o que ela escreve, o que imprime e os blocos que esta página cita com os ficheiros aí guardados, e valida e compila o que a importação escreveu.
Gerar o exemplo
É possível executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example import-agent-frameworkDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta; o seguinte, abaixo, entra na pasta source da nova pasta, que contém o que esta página importa e é onde a importação é executada:
cd import-agent-framework
O projeto
Uma aplicação criada com o Agent Framework pode carregar um agente a partir de um agente declarativo: um documento YAML do tipo Prompt que indica o modelo do agente, as suas instruções e as suas ferramentas. Este, escrito para este guia, indica o gpt-4.1-mini da OpenAI e o servidor MCP que o Microsoft Learn publica:
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_fetchA chave do modelo é escrita como =Env.OPENAI_API_KEY, pelo que o ficheiro não contém nenhuma chave. O Agent Framework lê essa expressão da variável de ambiente OPENAI_API_KEY apenas onde a aplicação carrega o agente declarativo com AgentFactory(safe_mode=False), a definição de segurança própria do Agent Framework, e está presente um runtime .NET; caso contrário, a chave é o texto da expressão tal como está escrito. O código da aplicação, que carrega o agente declarativo, nunca é lido pela importação e não faz parte do exemplo. Ao lado do ficheiro, um .aggrega-config.yaml torna a pasta um espaço de trabalho:
# 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.aiA importação referencia os Components de agente do Agent Framework e de modelo da OpenAI do catálogo, e --target rascunha um Manifest a partir das Recipes dele. O espaço de trabalho não indica nenhuma pasta de catálogo, pelo que a importação lê o catálogo da biblioteca padrão a partir do registo do qual obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação obtém, verifica e guarda na cache de conteúdo do espaço de trabalho, e que é identificado pelo seu digest no ficheiro de registo que a importação escreve junto aos seus rascunhos. Um espaço de trabalho que indica as suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS ou em workspace.catalog_dirs — importa antes face a essas.
O que a importação pergunta
Um agente declarativo indica o seu modelo, nunca a imagem em que a aplicação é executada: essa imagem compila-se a partir do projeto. O catálogo não contém nenhuma imagem predefinida para uma aplicação criada com o Agent Framework, pelo que a importação a pede. Executada num terminal sem resposta disponível, pergunta:
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.>e escreve a resposta nos rascunhos e em import-answers.yaml, junto a support-agent.yaml, para que a importação seguinte a leia daí e não pergunte nada. Sem terminal — em integração contínua ou através de um pipe — não pergunta nada: escreve o ficheiro com a chave vazia e para, indicando o ficheiro. O exemplo já contém o ficheiro, com a imagem respondida, ghcr.io/example/support-agent:1.0.0, que representa a imagem que se compila:
# 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"A segunda resposta destina-se a uma compilação para Kubernetes, com --target helm: aí o agente lê a chave da OpenAI de um Secret do Kubernetes, e a resposta é o nome do Secret, openai-api-key, nunca a chave. Uma compilação para Docker Compose lê antes a chave a partir da shell, pelo que esta importação não usa essa resposta. O ficheiro de respostas da importação descreve o ficheiro, as perguntas e as regras para a resposta a um segredo.
aggrega import lista todas as flags que o comando aceita, entre elas --answers, que indica um ficheiro de respostas guardado noutro local.
Entre em source:
cd sourceExecutar a importação
Indique o ficheiro do agente declarativo. A importação lê cada agente declarativo como um ficheiro próprio, nunca como um diretório:
aggrega import support-agent.yaml --target composeNa saída padrão, lista o que escreveu:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa saída de erro padrão, com <workspace> a representar a pasta em que a executou:
[… 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)
- A linha
warnindica um valor que pode conter uma chave — o endereço de um servidor MCP — e diz que é levado tal como está escrito. Este endereço não contém nenhuma. - A linha
infoindica a resposta que os rascunhos para Docker Compose não usam, guardada no ficheiro de respostas para uma compilação para Kubernetes. - As linhas
mappeddizem que o agente é uma instância do agente do Agent Framework da biblioteca padrão,core/ai-agent/agent-framework, e o seu modelo uma instância decore/ai-model/openai. O nível delas éNONE: a importação do Agent Framework referencia estes Components pelo que o agente declarativo indica, em vez de comparar cada um com o catálogo. - A linha
made no choiceé o servidor MCP, para o qual a importação não rascunha nenhum Component, pelo motivo que os comentários emaggregate.yamlindicam. - A linha
Pull completeé a importação a obter aquilo de que a Release rascunhada depende, como fazaggrega pull, pararelease.lock, para que os rascunhos sejam validados e compilados de imediato. Com--offline, a importação não obtém nada e indica o comandoaggrega pulla executar.
O que a importação escreve
O Aggregate, a Release e o Manifest chamam-se imported/supportagent, a partir do name do agente, SupportAgent, reduzido a supportagent — o seu displayName não é lido — no namespace que a definição target_namespace do importador estabelece, imported, salvo se definir outro (Definições).
aggregate.yaml — o agente, ligado ao seu modelo com a chave que apresenta declarada na ligação, e o 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"O servidor MCP não é um Component nem uma ligação do agente: o Agent Framework envia-o ao fornecedor do modelo como uma ferramenta alojada, e é o fornecedor, não a aplicação, que o alcança no seu url, que tem, por isso, de ser acessível a partir do fornecedor. As instruções, as opções dos pedidos ao modelo e a descrição, o modo de aprovação e as ferramentas permitidas do servidor permanecem no agente declarativo, que a aplicação lê; os comentários indicam cada um. A API da OpenAI é um serviço alojado, pelo que o Component do agente recusa uma ligação a ela que não transporte nenhuma credencial; a ligação declara uma, sob a chave OPENAI_API_KEY, a variável a partir da qual o agente declarativo lê a sua chave.
release.yaml — o ambiente, a imagem, a porta publicada e a origem da chave:
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: {}O ambiente, development, é um valor predefinido que a importação escreve porque nenhum agente declarativo indica um; altere-o quando a Release fizer o deploy noutro lugar. A imagem é a resposta que a importação leu de import-answers.yaml. O agente é publicado no endereço de loopback da máquina, na porta 8000, reencaminhando para a porta em que o seu programa escuta, infra.port, 8000 se não for definida. A chave é a referência a variável ${OPENAI_API_KEY}, com o nome da variável que o agente declarativo lê, nunca um valor. O endereço do servidor MCP é escrito tal como o agente declarativo o declara, para revisão, e não é definido em mais nenhum lugar: o Agent Framework entrega-o ao fornecedor no seu pedido ao modelo.
manifest.yaml — a Recipe Compose do agente e do modelo, e a realização que escreve a referência a variável da chave no ficheiro 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 regista, por digest, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registo do que a importação escreveu, que um aggrega import --sync posterior lê.
Validar e compilar
aggrega validate --release release.yamlaggrega build --release release.yaml

A validação 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)e o build, com <workspace> a representar a pasta onde o executou:
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>/distA linha notice é apenas informativa: a Feature de segredo aceita o seu origin dos values do Aggregate ou da infra da Release, e a notificação informa que uma folha está declarada em ambos. Não altera nenhum veredicto.
O serviço do agente em 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: - composeA aplicação recebe o endereço do modelo, o seu nome e a sua chave nas variáveis que os clientes OpenAI do Agent Framework leem, pelo que o =Env.OPENAI_API_KEY do agente declarativo lê a chave que a Release anexou onde a aplicação carrega o agente como O projeto descreve. Nenhuma variável contém o endereço do servidor MCP, que o fornecedor alcança. O modelo não recebe um serviço próprio: o agente alcança a API da OpenAI no próprio endereço desta. A chave é uma referência de variável, preenchida a partir da shell quando a stack arranca. O serviço publica a sua porta apenas em 127.0.0.1.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole nele este prompt.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do Workspace ainda não contiver uma pasta `import-agent-framework`, chame uma vez a ferramenta `scaffold` com `example` definido como `import-agent-framework` e sem `dir`: esta escreve o exemplo numa nova pasta `import-agent-framework`, cuja pasta `source` contém o que esta página importa. Depois, chame a ferramenta `import` com `workspace_root` definido como `import-agent-framework/source`, `source` definido como `support-agent.yaml` e `target` definido como `compose`: esta lê as respostas de que precisa em `import-answers.yaml`, ao lado de `support-agent.yaml`, escreve os seus rascunhos em `import-agent-framework/source` e obtém aquilo de que estes precisam. Depois, chame a ferramenta `validate` com `workspace_root` definido como `import-agent-framework/source` e `release` definido como `release.yaml`, e a ferramenta `build` com `workspace_root` definido como `import-agent-framework/source`, `release` definido como `release.yaml` e `write` definido como true. Indique-me que ficheiros a compilação escreveu; estão em `import-agent-framework/source/dist/`.Abrir no VS Code
Com a extensão do Aggrega para Visual Studio Code instalada, abra no VS Code a pasta import-agent-framework/source, onde a importação escreveu os seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, pelo que o editor a seleciona automaticamente e verifica os rascunhos face a essa Release à medida que são editados, assinalando o que encontra no ficheiro e no painel Problemas. Aggrega: Show topology graph, na paleta de comandos, desenha os componentes da Release e as ligações entre eles. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull atuam sobre a mesma Release, e cada um é também um botão no painel Commands da vista Aggrega na barra de atividade; o Build escreve os seus ficheiros no dist/ da pasta. Utilizar o Aggrega no Visual Studio Code trata do resto.
Execução
A imagem é construída a partir do projeto, com um Dockerfile próprio: o código da aplicação, com o Agent Framework instalado e o agente declarativo lá dentro. O Docker Compose executa o próprio comando da imagem como o serviço do agente, uma vez que a Recipe não define nenhum, pelo que esse comando tem de continuar em execução, e tem de atender pedidos se pretender alcançar o agente. O seu programa decide o endereço, a rota e a resposta.
A execução abaixo usou uma imagem deste tipo: Python com os pacotes agent-framework-core, agent-framework-openai e agent-framework-declarative do Agent Framework, um runtime .NET — a imagem definiu DOTNET_ROOT como o diretório dele e DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 — support-agent.yaml e, como comando da imagem, um pequeno servidor HTTP próprio do programa na porta 8000. O servidor carrega o agente declarativo com AgentFactory(safe_mode=False), pelo que o seu =Env.OPENAI_API_KEY lê a chave que o build entrega, e executa o agente uma vez por cada POST /ask. Construa a sua imagem na raiz do projeto, escreva o nome dela no lugar de ghcr.io/example/support-agent:1.0.0 em import-answers.yaml e volte a importar com --sync, que escreve a nova resposta nos rascunhos e volta a fazer o pull; depois faça o build:
docker build -t docs-assistant:local .aggrega import support-agent.yaml --syncaggrega build --release release.yamlCom docs-assistant:local como resposta, a sincronização indica o único valor que alterou, entre as linhas que imprime:
changed spec.components.supportagent.infra.image in release.yamlDepois, defina a chave na shell e inicie a stack:
export OPENAI_API_KEY='your OpenAI key'docker compose -p docs-assistant -f dist/compose/docker-compose.yaml up -d --wait-p dá nome ao projeto, como explica o passo de execução de Como decorre uma importação.
Testar
O pedido abaixo chega ao programa que a imagem deste guia executa: o agente declarativo por trás de um pequeno servidor HTTP na porta 8000, que responde a POST /ask. O programa de cada utilizador decide a sua própria rota e resposta. Envie-o para http://127.0.0.1:8000, o endereço que published_port publica, assim que o programa estiver à escuta, alguns segundos depois de a stack arrancar:
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]"}A execução definiu OPENAI_API_KEY como um valor fictício, pelo que a resposta é a recusa da OpenAI, transmitida pelo programa. A chave que a OpenAI recusou é esse valor fictício, apresentado mascarado, pelo que o =Env.OPENAI_API_KEY do agente declarativo a leu do ambiente que a compilação fornece.
Pare a stack com:
docker compose -p docs-assistant -f dist/compose/docker-compose.yaml downNo Kubernetes, importe com --target helm e envie a imagem para um registo a partir do qual o cluster obtém imagens, indicando-a em import-answers.yaml. Depois, crie o Secret openai-api-key e aplique a compilação, como descreve o passo de execução de Como decorre uma importação. O Deployment do agente não tem nenhum Service, pelo que é necessário reencaminhar uma porta local para ele. O comando fica em execução até ser interrompido:
kubectl port-forward deploy/supportagent 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000Noutro terminal, envie o mesmo pedido para a porta reencaminhada:
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]"}