Import agenta deklaratywnego Microsoft Agent Framework
Ten przewodnik importuje agenta deklaratywnego Microsoft Agent Framework — asystenta odpowiadającego na pytania na podstawie dokumentacji przeszukiwanej przez serwer MCP — i kompiluje aplikację dla Docker Compose. Import tworzy wersję roboczą każdego pliku, który odczytuje kompilacja: agenta i jego model, klucz, który agent przedstawia modelowi, jako odwołanie do zmiennej, oraz realizacje każdego z nich. Pyta jeden raz o jedyną wartość, której nie zawiera żaden agent deklaratywny: obraz, w którym działa aplikacja. Każdy plik i każdy blok wyjścia poniżej pochodzi z rzeczywistego uruchomienia; agent deklaratywny i każdy etap przewodnika znajdują się w przykładzie import-agent-framework, w którym skrypt kontrolny ponownie uruchamia import, porównuje to, co zapisuje, to, co wypisuje, oraz bloki cytowane na tej stronie z przechowywanymi tam plikami, a także waliduje i kompiluje to, co zapisał import.
Generowanie przykładu
Ten import można uruchomić poleceniami z tej strony albo zlecić to asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example import-agent-frameworkNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu; kolejne, poniżej, przechodzi do folderu source w nowym folderze, który zawiera to, co importuje ta strona, i w którym uruchamia się import:
cd import-agent-framework
Projekt
Aplikacja zbudowana na Agent Framework może załadować agenta z agenta deklaratywnego: dokumentu YAML rodzaju Prompt, który wskazuje model agenta, jego instrukcje i narzędzia. Ten, napisany na potrzeby przewodnika, wskazuje gpt-4.1-mini od OpenAI i serwer MCP publikowany przez Microsoft Learn:
kind: Promptname: SupportAgentdisplayName: Support Assistantdescription: Answers a customer's question about the product from its documentation.instructions: You answer customers' questions about the product, from its documentation only.model: id: gpt-4.1-mini provider: OpenAI apiType: Responses options: temperature: 0.2 connection: kind: key key: =Env.OPENAI_API_KEYtools: - kind: mcp name: microsoft_learn description: Search Microsoft's documentation on Microsoft Learn. url: https://learn.microsoft.com/api/mcp approvalMode: kind: never allowedTools: - microsoft_docs_search - microsoft_docs_fetchKlucz modelu jest zapisany jako =Env.OPENAI_API_KEY, więc plik nie zawiera żadnego klucza. Agent Framework odczytuje to wyrażenie ze zmiennej środowiskowej OPENAI_API_KEY tylko tam, gdzie aplikacja ładuje agenta deklaratywnego za pomocą AgentFactory(safe_mode=False), własnego ustawienia bezpieczeństwa Agent Framework, i obecne jest środowisko uruchomieniowe .NET; w przeciwnym razie kluczem jest tekst wyrażenia w zapisanej postaci. Kod aplikacji, który ładuje agenta deklaratywnego, nigdy nie jest odczytywany przez import i nie jest częścią przykładu. Obok pliku znajduje się plik .aggrega-config.yaml, który czyni folder obszarem roboczym:
# 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.aiImport odwołuje się do encji Components z katalogu dla agenta Agent Framework i modelu OpenAI, a --target tworzy roboczą encję Manifest na podstawie jego encji Recipes. Obszar roboczy nie wskazuje żadnego folderu katalogu, więc import odczytuje katalog biblioteki standardowej z rejestru, z którego pobiera swój importer: podpisaną migawkę opublikowanego katalogu, pobraną, zweryfikowaną i przechowywaną w pamięci podręcznej treści obszaru roboczego przez pierwszy import oraz wskazaną przez jej skrót w zapisie, który import umieszcza obok swoich szkiców. Obszar roboczy, który wskazuje własne foldery katalogu — w AGGREGA_CATALOG_DIRS lub w workspace.catalog_dirs — importuje zamiast tego względem nich.
O co pyta import
Agent deklaratywny wskazuje swój model, nigdy obraz, w którym działa aplikacja: ten obraz buduje się z własnego projektu. Katalog nie zawiera domyślnego obrazu dla aplikacji zbudowanej na Agent Framework, dlatego import o niego pyta. Uruchomiony w terminalu bez gotowej odpowiedzi, pyta:
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.>i zapisuje odpowiedź w szkicach oraz w import-answers.yaml, obok support-agent.yaml, dzięki czemu następny import odczytuje ją stamtąd i o nic nie pyta. Bez terminala — w ciągłej integracji lub przez potok — o nic nie pyta: zapisuje plik z pustym kluczem i zatrzymuje się, wskazując plik. Przykład zawiera już ten plik z odpowiedzią dla obrazu, ghcr.io/example/support-agent:1.0.0, który zastępuje budowany obraz:
# 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"Druga odpowiedź dotyczy kompilacji dla Kubernetes z --target helm: tam agent odczytuje klucz OpenAI z obiektu Secret Kubernetes, a odpowiedzią jest nazwa obiektu Secret, openai-api-key, nigdy sam klucz. Kompilacja dla Docker Compose odczytuje natomiast klucz z powłoki, więc ten import nie używa tej odpowiedzi. Plik odpowiedzi importu opisuje plik, pytania i zasady dotyczące odpowiedzi na sekret.
aggrega import wymienia każdą flagę przyjmowaną przez polecenie, w tym --answers, która wskazuje plik odpowiedzi przechowywany gdzie indziej.
Należy przejść do source:
cd sourceUruchomienie importu
Należy wskazać plik agenta deklaratywnego. Import odczytuje każdego agenta deklaratywnego jako osobny plik, nigdy jako folder:
aggrega import support-agent.yaml --target composeNa standardowym wyjściu wymienia to, co zapisał:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonNa standardowym wyjściu błędów, gdzie <workspace> oznacza folder, w którym go uruchomiono:
[… 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)
- Wiersz
warnwskazuje wartość, która może zawierać klucz — adres serwera MCP — i informuje, że jest ona przenoszona w postaci, w jakiej została zapisana. Ten adres żadnego nie zawiera. - Wiersz
infowskazuje odpowiedź, której nie używają szkice dla Docker Compose, przechowywaną w pliku odpowiedzi na potrzeby kompilacji dla Kubernetes. - Wiersze
mappedinformują, że agent jest instancją agenta Agent Framework z biblioteki standardowej,core/ai-agent/agent-framework, a jego model instancjącore/ai-model/openai. Ich poziom toNONE: import Agent Framework odwołuje się do tych encji Components na podstawie tego, co wskazuje agent deklaratywny, zamiast porównywać każdą z katalogiem. - Wiersz
made no choiceto serwer MCP, dla którego import nie tworzy żadnej encji Component, z powodu podanego w komentarzach waggregate.yaml. - Wiersz
Pull completeoznacza, że import pobiera to, od czego zależy szkic encji Release, tak jak robi toaggrega pull, dorelease.lock, dzięki czemu szkice od razu przechodzą walidację i budowanie. Z--offlineimport niczego nie pobiera i podaje polecenieaggrega pull, które należy uruchomić.
Co zapisuje import
Encje Aggregate, Release i Manifest otrzymują nazwę imported/supportagent od pola name agenta, SupportAgent, sprowadzonego do supportagent — jego displayName nie jest odczytywane — w przestrzeni nazw określonej przez ustawienie target_namespace importera, imported, o ile nie ustawi się innej (Ustawienia).
aggregate.yaml — agent połączony ze swoim modelem, z kluczem, który przedstawia, zadeklarowanym w połączeniu, oraz ten model:
# 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"Serwer MCP nie jest encją Component ani połączeniem agenta: Agent Framework wysyła go do dostawcy modelu jako narzędzie hostowane, a to dostawca, a nie aplikacja, łączy się z nim pod jego adresem url, który w związku z tym musi być osiągalny od strony dostawcy. Instrukcje, opcje żądań modelu oraz opis, tryb zatwierdzania i dozwolone narzędzia serwera pozostają w agencie deklaratywnym, który odczytuje aplikacja; komentarze wymieniają każdy z tych elementów. API OpenAI jest usługą hostowaną, więc encja Component agenta odrzuca połączenie z nim, które nie niesie żadnych poświadczeń; połączenie deklaruje je pod kluczem OPENAI_API_KEY, czyli zmienną, z której agent deklaratywny odczytuje swój klucz.
release.yaml — środowisko, obraz, opublikowany port i źródło klucza:
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: {}Środowisko, development, to wartość domyślna, którą zapisuje import, ponieważ żaden agent deklaratywny nie wskazuje środowiska; należy ją zmienić, jeśli encja Release wdraża gdzie indziej. Obraz to odpowiedź, którą import odczytał z import-answers.yaml. Agent jest publikowany na adresie pętli zwrotnej maszyny, na porcie 8000, z przekierowaniem do portu, na którym nasłuchuje jego program, infra.port, domyślnie 8000. Klucz to odwołanie do zmiennej ${OPENAI_API_KEY}, nazwane od zmiennej odczytywanej przez agenta deklaratywnego, nigdy wartość. Adres serwera MCP jest zapisany tak, jak określa go agent deklaratywny, do przeglądu, i nie jest ustawiany nigdzie indziej: Agent Framework przekazuje go dostawcy w swoim żądaniu do modelu.
manifest.yaml — encja Recipe dla Compose agenta i modelu oraz realizacja, która zapisuje odwołanie do zmiennej klucza w pliku Compose w zapisanej postaci:
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 rejestruje, według digestu, encje katalogu, na które została rozwiązana encja Release, a .aggrega-import.json to zapis tego, co utworzył import, odczytywany przez późniejsze aggrega import --sync.
Walidacja i kompilacja
aggrega validate --release release.yamlaggrega build --release release.yaml

Walidacja wypisuje:
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)oraz build, gdzie <workspace> oznacza folder, w którym go uruchomiono:
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>/distWiersz notice ma charakter informacyjny: encja Feature sekretu przyjmuje swoje origin z values encji Aggregate lub z infra encji Release, a komunikat informuje, że jeden liść jest zadeklarowany w obu miejscach. Nie zmienia żadnego werdyktu.
Usługa agenta w 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: - composeAplikacja otrzymuje adres modelu, jego nazwę i klucz w zmiennych odczytywanych przez klientów OpenAI z Agent Framework, więc =Env.OPENAI_API_KEY agenta deklaratywnego odczytuje klucz dołączony przez encję Release tam, gdzie aplikacja ładuje agenta w sposób opisany w sekcji Projekt. Żadna zmienna nie przenosi adresu serwera MCP, z którym łączy się dostawca. Model nie otrzymuje własnej usługi: agent łączy się z API OpenAI pod jego własnym adresem. Klucz jest odwołaniem do zmiennej, wypełnianym z powłoki przy uruchamianiu stosu. Usługa publikuje swój port wyłącznie na 127.0.0.1.
Z asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić do niego ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `import-agent-framework`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `import-agent-framework` i bez `dir`: zapisuje ono przykład w nowym folderze `import-agent-framework`, którego folder `source` zawiera to, co importuje ta strona. Następnie wywołaj narzędzie `import` z `workspace_root` ustawionym na `import-agent-framework/source`, `source` ustawionym na `support-agent.yaml` i `target` ustawionym na `compose`: odczytuje ono potrzebne odpowiedzi z `import-answers.yaml` obok `support-agent.yaml`, zapisuje wersje robocze w `import-agent-framework/source` i pobiera to, czego one potrzebują. Następnie wywołaj narzędzie `validate` z `workspace_root` ustawionym na `import-agent-framework/source` i `release` ustawionym na `release.yaml` oraz narzędzie `build` z `workspace_root` ustawionym na `import-agent-framework/source`, `release` ustawionym na `release.yaml` i `write` ustawionym na true. Podaj, które pliki zapisała kompilacja; znajdują się w `import-agent-framework/source/dist/`.Otwieranie w VS Code
Po zainstalowaniu rozszerzenia Aggrega dla Visual Studio Code należy otworzyć w VS Code folder import-agent-framework/source, w którym import zapisał wersje robocze. Folder zawiera jedną encję Release, wersję roboczą release.yaml, więc edytor sam ją wybiera i podczas edycji sprawdza wersje robocze względem tej encji Release, oznaczając znalezione problemy w pliku i w panelu Problemy. Aggrega: Show topology graph w palecie poleceń rysuje komponenty encji Release i połączenia między nimi. Aggrega: Build, Aggrega: Preview build i Aggrega: Pull działają na tej samej encji Release, a każde z nich jest też przyciskiem w panelu Commands widoku Aggrega na pasku działań; Build zapisuje swoje pliki w dist/ folderu. Resztę omawia Używanie Aggrega w Visual Studio Code.
Uruchomienie
Obraz buduje się z projektu za pomocą własnego pliku Dockerfile: kod aplikacji z zainstalowanym Agent Framework i agentem deklaratywnym w środku. Docker Compose uruchamia własne polecenie obrazu jako usługę agenta, ponieważ encja Recipe żadnego nie ustawia, więc to polecenie musi działać bez przerwy i musi obsługiwać żądania, jeśli agent ma być osiągalny. O adresie, trasie i odpowiedzi decyduje własny program.
Poniższe uruchomienie korzystało z takiego obrazu: Python z pakietami agent-framework-core, agent-framework-openai i agent-framework-declarative z Agent Framework, środowisko uruchomieniowe .NET — obraz ustawiał DOTNET_ROOT na jego katalog oraz DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 — support-agent.yaml oraz, jako polecenie obrazu, mały własny serwer HTTP programu na porcie 8000. Serwer ładuje agenta deklaratywnego za pomocą AgentFactory(safe_mode=False), więc jego =Env.OPENAI_API_KEY odczytuje klucz dostarczany przez build, i uruchamia agenta raz dla każdego POST /ask. Należy zbudować obraz w katalogu głównym projektu, wpisać jego nazwę w miejsce ghcr.io/example/support-agent:1.0.0 w import-answers.yaml i ponownie zaimportować z --sync, co zapisuje nową odpowiedź w szkicach i ponownie wykonuje pull; następnie uruchomić build:
docker build -t docs-assistant:local .aggrega import support-agent.yaml --syncaggrega build --release release.yamlGdy odpowiedzią jest docs-assistant:local, synchronizacja wskazuje, wśród wypisywanych wierszy, jedyną zmienioną wartość:
changed spec.components.supportagent.infra.image in release.yamlNastępnie należy ustawić klucz w powłoce i uruchomić stack:
export OPENAI_API_KEY='your OpenAI key'docker compose -p docs-assistant -f dist/compose/docker-compose.yaml up -d --wait-p nadaje nazwę projektowi, jak wyjaśnia krok uruchamiania w Jak przebiega import.
Testowanie
Poniższe żądanie trafia do programu uruchamianego przez obraz z tego przewodnika: agenta deklaratywnego za małym serwerem HTTP na porcie 8000, który odpowiada na POST /ask. Własny program sam decyduje o swojej ścieżce i odpowiedzi. Należy je wysłać na http://127.0.0.1:8000, adres publikowany przez published_port, gdy program już nasłuchuje, kilka sekund po uruchomieniu stosu:
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]"}W tym uruchomieniu OPENAI_API_KEY ustawiono na wartość zastępczą, więc odpowiedź to odmowa OpenAI przekazana przez program. Klucz odrzucony przez OpenAI to właśnie ta wartość zastępcza, pokazana w postaci zamaskowanej, więc =Env.OPENAI_API_KEY agenta deklaratywnego odczytał go ze środowiska dostarczanego przez kompilację.
Stack zatrzymuje się poleceniem:
docker compose -p docs-assistant -f dist/compose/docker-compose.yaml downW Kubernetes należy zaimportować z --target helm i wypchnąć obraz do rejestru, z którego pobiera klaster, podając jego nazwę w import-answers.yaml. Następnie należy utworzyć Secret openai-api-key i zastosować kompilację, jak opisuje krok uruchamiania w Jak przebiega import. Deployment agenta nie ma obiektu Service, więc należy przekierować do niego lokalny port. Polecenie działa, dopóki się go nie zatrzyma:
kubectl port-forward deploy/supportagent 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000Z innego terminala należy wysłać to samo żądanie na przekierowany port:
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]"}