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 com base na documentação que pesquisa por meio de um servidor MCP — e compila a aplicação para Docker Compose. A importação rascunha todo arquivo que a compilação lê: o agente e seu modelo, a chave que o agente apresenta ao modelo como referência de variável, e as realizações de cada um. Ela pergunta uma única vez pelo único valor que nenhum agente declarativo contém, a imagem em que sua aplicação é executada. Todo arquivo e todo bloco de saída abaixo vê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 executa a importação novamente, compara o que ela grava, o que imprime e os blocos que esta página cita com os arquivos mantidos lá, e valida e compila o que a importação gravou.
Gerar o exemplo
Você pode executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute para você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example import-agent-frameworkEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova; o seguinte, abaixo, entra na pasta source da pasta nova, 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 nomeia o modelo do agente, suas instruções e suas ferramentas. Este, escrito para este guia, nomeia 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, então o arquivo não contém nenhuma chave. O Agent Framework lê essa expressão da variável de ambiente OPENAI_API_KEY somente onde a aplicação carrega o agente declarativo com AgentFactory(safe_mode=False), a própria configuração de segurança do Agent Framework, e há um runtime .NET presente; 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 arquivo, 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, então a importação lê o catálogo da biblioteca padrão do registro do qual busca seu importador: um snapshot assinado do catálogo publicado, que a primeira importação busca, verifica e guarda no cache de conteúdo do espaço de trabalho, e que é identificado pelo digest no arquivo de registro que a importação grava ao lado dos rascunhos. Um espaço de trabalho que indica as próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS ou em workspace.catalog_dirs — importa em relação a elas.
O que a importação pergunta
Um agente declarativo nomeia seu modelo, nunca a imagem em que a aplicação é executada: essa imagem você compila a partir do seu projeto. O catálogo não tem imagem padrão para uma aplicação criada com o Agent Framework, então a importação a pede. Executada em um terminal sem uma resposta à mão, ela 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 grava a resposta nos rascunhos e em import-answers.yaml, ao lado de support-agent.yaml, para que a próxima importação a leia de lá e não pergunte nada. Sem terminal — em integração contínua ou por meio de um pipe — ela não pergunta nada: grava o arquivo com a chave vazia e para, nomeando o arquivo. O exemplo já contém o arquivo, com a imagem respondida, ghcr.io/example/support-agent:1.0.0, que representa a imagem que você 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 é para uma compilação para Kubernetes, com --target helm: ali 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ê a chave do seu shell, então esta importação não usa essa resposta. O arquivo de respostas da importação descreve o arquivo, as perguntas e as regras para a resposta de um segredo.
aggrega import lista todas as flags que o comando aceita, entre elas --answers, que nomeia um arquivo de respostas mantido em outro lugar.
Entre em source:
cd sourceExecutar a importação
Indique o arquivo do agente declarativo. A importação lê cada agente declarativo como um arquivo próprio, nunca como um diretório:
aggrega import support-agent.yaml --target composeNa saída padrão, ela lista o que gravou:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa saída de erro padrão, com <workspace> representando a pasta em que você 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
warnnomeia um valor que pode conter uma chave — o endereço de um servidor MCP — e diz que ele é levado tal como está escrito. Este endereço não contém nenhuma. - A linha
infonomeia a resposta que os rascunhos do Docker Compose não usam, mantida no arquivo 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 seu modelo uma instância decore/ai-model/openai. O nível delas éNONE: a importação do Agent Framework referencia esses Components pelo que o agente declarativo nomeia, 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.yamlinformam. - A linha
Pull completeé a importação buscando aquilo de que a Release rascunhada depende, como fazaggrega pull, emrelease.lock, para que os rascunhos sejam validados e compilados imediatamente. Com--offline, a importação não busca nada e indica o comandoaggrega pulla executar.
O que a importação grava
O Aggregate, a Release e o Manifest se chamam imported/supportagent, a partir do name do agente, SupportAgent, reduzido a supportagent — seu displayName não é lido — sob o namespace definido pela configuração target_namespace do importador, imported, a menos que você defina outro (Configurações).
aggregate.yaml — o agente, ligado ao seu modelo com a chave que apresenta declarada na conexã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 conexão do agente: o Agent Framework o envia ao provedor do modelo como uma ferramenta hospedada, e é o provedor, não a aplicação, que o alcança em sua url, que portanto precisa ser acessível a partir do provedor. As instruções, as opções das requisições 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 nomeiam cada um. A API da OpenAI é um serviço hospedado, então o Component do agente recusa uma conexão com ela que não carregue nenhuma credencial; a conexão declara uma, sob a chave OPENAI_API_KEY, a variável da qual o agente declarativo lê sua chave.
release.yaml — o ambiente, a imagem, a porta publicada e de onde vem a 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 padrão que a importação grava porque nenhum agente declarativo nomeia um; altere-o quando a Release fizer o deploy em outro lugar. A imagem é a resposta que a importação leu de import-answers.yaml. O agente é publicado no endereço de loopback da sua máquina, na porta 8000, encaminhando para a porta em que seu programa escuta, infra.port, 8000, a menos que você a defina. A chave é a referência a variável ${OPENAI_API_KEY}, nomeada a partir 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 nenhum outro lugar: o Agent Framework o entrega ao provedor em sua requisição 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 arquivo 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, as entidades do catálogo para as quais a Release foi resolvida, e .aggrega-import.json é o registro do que a importação gravou, 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> representando a pasta em que você 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 seu origin dos values do Aggregate ou da infra da Release, e a notificação informa que uma folha está declarada em ambos. Ela não altera nenhum veredito.
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, seu nome e sua chave nas variáveis que os clientes OpenAI do Agent Framework leem, de modo 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 leva o endereço do servidor MCP, que o provedor 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 dela. A chave é uma referência de variável, preenchida a partir do seu shell quando a stack é iniciada. O serviço publica 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 este prompt nele.
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`: ela grava o exemplo em uma nova pasta `import-agent-framework`, cuja pasta `source` contém o que esta página importa. Em seguida, chame a ferramenta `import` com `workspace_root` definido como `import-agent-framework/source`, `source` definido como `support-agent.yaml` e `target` definido como `compose`: ela lê as respostas de que precisa em `import-answers.yaml`, ao lado de `support-agent.yaml`, grava seus rascunhos em `import-agent-framework/source` e baixa o que eles precisam. Em seguida, 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. Diga-me quais arquivos o build gravou; eles estão em `import-agent-framework/source/dist/`.Abra 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 gravou seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, então o editor a seleciona para você e verifica os rascunhos em relação a essa Release enquanto você os edita, marcando o que encontra no arquivo e no painel Problemas. Aggrega: Show topology graph, na paleta de comandos, desenha os componentes da Release e as conexõ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 visualização Aggrega na barra de atividades; o Build grava seus arquivos no dist/ da pasta. Usar o Aggrega no Visual Studio Code cobre o restante.
Execução
Você constrói a imagem a partir do projeto, com um Dockerfile seu: o código da aplicação, com o Agent Framework instalado e o agente declarativo dentro. O Docker Compose executa o próprio comando da imagem como o serviço do agente, já que a Recipe não define nenhum, então esse comando precisa continuar em execução, e precisa atender requisições se você quiser alcançar o agente. Seu programa decide o endereço, a rota e a resposta.
A execução abaixo usou uma imagem assim: 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), de modo que seu =Env.OPENAI_API_KEY lê a chave que o build entrega, e executa o agente uma vez para cada POST /ask. Construa 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 importe novamente com --sync, que grava a nova resposta nos rascunhos e faz o pull novamente; 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 nomeia o único valor que alterou, entre as linhas que imprime:
changed spec.components.supportagent.infra.image in release.yamlEm seguida, defina a chave no seu 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 a etapa de execução de Como uma importação é executada.
Teste
A requisição abaixo chega ao programa que a imagem deste passo a passo executa: o agente declarativo atrás de um pequeno servidor HTTP na porta 8000, respondendo a POST /ask. O seu próprio programa decide a própria rota e a resposta. Envie-a para http://127.0.0.1:8000, o endereço que published_port publica, assim que o programa estiver escutando, alguns segundos depois de a stack iniciar:
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, então a resposta é a recusa da OpenAI, repassada pelo programa. A chave que a OpenAI recusou é esse valor fictício, exibido mascarado, então o =Env.OPENAI_API_KEY do agente declarativo a leu do ambiente que o build 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 registry do qual o seu cluster baixa imagens, indicando-a em import-answers.yaml. Em seguida, crie o Secret openai-api-key e aplique o build, como descreve a etapa de execução de Como uma importação é executada. O Deployment do agente não tem Service, então encaminhe uma porta local para ele. O comando fica em execução até você interrompê-lo:
kubectl port-forward deploy/supportagent 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000Em outro terminal, envie a mesma requisição para a porta encaminhada:
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]"}