Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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:

Terminal window
aggrega scaffold --example import-agent-framework

Em 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:

Terminal window
cd import-agent-framework

A pasta source do exemplo gerado aberta no Visual Studio Code, mostrando o prompt agent SupportAgent com seu modelo OpenAI e sua ferramenta MCP do Microsoft Learn.

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: Prompt
name: SupportAgent
displayName: Support Assistant
description: 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_KEY
tools:
- 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_fetch

A 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.ai

A 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:

Terminal window
cd source

Executar 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:

Terminal window
aggrega import support-agent.yaml --target compose

Na saída padrão, ela lista o que gravou:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Na 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 empty
info: 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 applied
mapped SupportAgent (agent) to core/ai-agent/agent-framework as a reference, NONE
mapped gpt-4.1-mini (model) to core/ai-model/openai as a reference, NONE
made no choice for SupportAgent#microsoft_learn (tool)
Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)

A importação executada a partir do editor: o Aggregate, a Release e o Manifest rascunhados aparecem ao lado do agente declarativo, a saída do Aggrega lista como o agente e seu modelo foram mapeados e os arquivos gravados, e uma notificação diz que a importação rascunhou 3 arquivos, reconhecidos como agent-framework.

  • A linha warn nomeia 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 info nomeia a resposta que os rascunhos do Docker Compose não usam, mantida no arquivo de respostas para uma compilação para Kubernetes.
  • As linhas mapped dizem 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 de core/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 em aggregate.yaml informam.
  • A linha Pull complete é a importação buscando aquilo de que a Release rascunhada depende, como faz aggrega pull, em release.lock, para que os rascunhos sejam validados e compilados imediatamente. Com --offline, a importação não busca nada e indica o comando aggrega pull a 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/v1beta1
kind: Aggregate
metadata:
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/v1beta1
kind: Release
metadata:
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/v1beta1
kind: Manifest
metadata:
name: imported/supportagent
version: 0.1.0
spec:
mappings:
components:
type:
core/ai-agent/agent-framework: compose/agent-framework
core/ai-model/openai: compose/openai
features:
type:
core/secret-value: compose/dotenv-secret

release.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

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

A Release em rascunho aberta no editor após validá-la, com a saída do Aggrega e uma notificação informando, ambas, que nenhum problema foi encontrado.

O build da Release em rascunho: uma pasta dist aparece no Explorer, a saída do Aggrega lista o arquivo do Docker Compose gravado e uma notificação informa que 1 arquivo foi gravado.

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>/dist

A 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:
- compose

A 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:

Terminal window
docker build -t docs-assistant:local .
aggrega import support-agent.yaml --sync
aggrega build --release release.yaml

Com 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.yaml

Em seguida, defina a chave no seu shell e inicie a stack:

Terminal window
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:

Terminal window
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:

Terminal window
docker compose -p docs-assistant -f dist/compose/docker-compose.yaml down

No 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:

Terminal window
kubectl port-forward deploy/supportagent 8000:8000
Forwarding from 127.0.0.1:8000 -> 8000
Forwarding from [::1]:8000 -> 8000

Em outro terminal, envie a mesma requisição para a porta encaminhada:

Terminal window
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]"}