Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler 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 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:

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

Depois, 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:

Terminal window
cd import-agent-framework

A pasta source do exemplo gerado aberta no Visual Studio Code, a mostrar o prompt agent SupportAgent com o seu modelo OpenAI e a 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 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: 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, 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.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, 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:

Terminal window
cd source

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

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

Na saída padrão, lista o que escreveu:

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

Na 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 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 o seu modelo foram mapeados e os ficheiros escritos, e uma notificação indica que a importação rascunhou 3 ficheiros, reconhecidos como agent-framework.

  • A linha warn indica 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 info indica a resposta que os rascunhos para Docker Compose não usam, guardada no ficheiro 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 o seu modelo uma instância de core/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 em aggregate.yaml indicam.
  • A linha Pull complete é a importação a obter aquilo de que a Release rascunhada depende, como faz aggrega pull, para release.lock, para que os rascunhos sejam validados e compilados de imediato. Com --offline, a importação não obtém nada e indica o comando aggrega pull a 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/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 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/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 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/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 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

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

A Release em rascunho aberta no editor depois de validada, com a saída do Aggrega e uma notificação a indicarem, ambas, que não foram encontrados problemas.

A compilação da Release em rascunho: aparece uma pasta dist no Explorador, a saída do Aggrega lista o ficheiro do Docker Compose escrito e uma notificação indica que foi escrito 1 ficheiro.

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

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

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

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 indica o único valor que alterou, entre as linhas que imprime:

changed spec.components.supportagent.infra.image in release.yaml

Depois, defina a chave na 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 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:

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

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

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

Noutro terminal, envie o mesmo pedido para a porta reencaminhada:

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