Імпорт декларативного агента Microsoft Agent Framework
У цьому покроковому прикладі імпортується декларативний агент Microsoft Agent Framework — асистент, що відповідає на запитання за документацією, яку шукає через сервер MCP, — і застосунок збирається для Docker Compose. Імпорт створює чернетку кожного файлу, який читає збирання: агента та його модель, ключ, який агент надає моделі, у вигляді посилання на змінну, і реалізації кожного з них. Він один раз запитує єдине значення, якого не містить жоден декларативний агент, — образ, у якому працює ваш застосунок. Кожен файл і кожен блок виводу нижче взято з реального запуску; декларативний агент і кожен етап прикладу містяться в прикладі import-agent-framework, де скрипт перевірки знову запускає імпорт, порівнює те, що він записує, що виводить, і блоки, які цитує ця сторінка, із файлами, що там зберігаються, а також перевіряє та збирає те, що записав імпорт.
Створення прикладу
Цей імпорт можна виконати командами з цієї сторінки або доручити його вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example import-agent-frameworkПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку; наступна, нижче, переходить у її теку source, яка містить те, що імпортує ця сторінка, і де виконується імпорт:
cd import-agent-framework
Проєкт
Застосунок, побудований на Agent Framework, може завантажити агента з декларативного агента — документа YAML виду Prompt, що називає модель агента, його інструкції та інструменти. Цей агент, написаний для цього прикладу, називає gpt-4.1-mini від OpenAI і сервер MCP, який публікує 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_fetchКлюч моделі записано як =Env.OPENAI_API_KEY, тож файл не містить ключа. Agent Framework читає цей вираз зі змінної середовища OPENAI_API_KEY лише там, де застосунок завантажує декларативного агента з AgentFactory(safe_mode=False), власним параметром безпеки Agent Framework, і присутнє середовище виконання .NET; інакше ключем є текст виразу в тому вигляді, у якому його записано. Код застосунку, який завантажує декларативного агента, імпорт ніколи не читає, і він не входить до прикладу. Поруч із файлом .aggrega-config.yaml робить теку робочим простором:
# 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Імпорт посилається на сутності Components каталогу для агента Agent Framework і моделі OpenAI, а --target створює чернетку сутності Manifest на основі сутностей Recipes каталогу. Робочий простір не вказує жодної теки каталогу, тож імпорт читає каталог стандартної бібліотеки з реєстру, з якого отримує свій імпортер: підписаний знімок опублікованого каталогу, який перший імпорт отримує, перевіряє та зберігає в кеші вмісту робочого простору і який названо за його дайджестом у записі, що імпорт записує поруч зі своїми чернетками. Робочий простір, який вказує власні теки каталогу — у AGGREGA_CATALOG_DIRS або в workspace.catalog_dirs, — натомість імпортує щодо них.
Що запитує імпорт
Декларативний агент називає свою модель, але ніколи не образ, у якому працює застосунок: цей образ ви збираєте зі свого проєкту. Каталог не містить типового образу для застосунку, побудованого на Agent Framework, тож імпорт запитує його. Запущений у терміналі без готової відповіді, він запитує:
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.>і записує відповідь у чернетки та в import-answers.yaml поруч із support-agent.yaml, тож наступний імпорт читає її звідти й нічого не запитує. Без термінала — у безперервній інтеграції або через конвеєр — він нічого не запитує: записує файл із порожнім ключем і зупиняється, називаючи файл. Приклад уже містить цей файл із відповіддю для образу, ghcr.io/example/support-agent:1.0.0, який заміняє образ, що ви збираєте:
# 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"Друга відповідь призначена для збирання для Kubernetes з --target helm: там агент читає ключ OpenAI з об’єкта Secret Kubernetes, а відповіддю є ім’я Secret, openai-api-key, ніколи не сам ключ. Збирання для Docker Compose натомість читає ключ із вашої оболонки, тож цей імпорт не використовує цю відповідь. Файл відповідей імпорту описує файл, запитання та правила для відповіді на секрет.
aggrega import перелічує кожен прапорець, який приймає команда, зокрема --answers, що вказує файл відповідей, збережений деінде.
Перейдіть у source:
cd sourceЗапуск імпорту
Назвіть файл декларативного агента. Імпорт читає кожного декларативного агента як окремий файл і ніколи як директорію:
aggrega import support-agent.yaml --target composeУ стандартний вивід він виводить перелік записаного:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonУ стандартний потік помилок, де <workspace> позначає теку, у якій ви його запустили:
[… 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)
- Рядок
warnназиває значення, яке може містити ключ, — адресу сервера MCP — і повідомляє, що воно переноситься як є. Ця адреса ключа не містить. - Рядок
infoназиває відповідь, яку не використовують чернетки для Docker Compose і яка зберігається у файлі відповідей для збирання для Kubernetes. - Рядки
mappedповідомляють, що агент є екземпляром агента Agent Framework зі стандартної бібліотеки,core/ai-agent/agent-framework, а його модель — екземпляромcore/ai-model/openai. Їхній рівень —NONE: імпорт Agent Framework посилається на ці сутності Components за тим, що називає декларативний агент, а не зважуючи кожну щодо каталогу. - Рядок
made no choice— це сервер MCP, для якого імпорт не створює чернетки жодної сутності Component, з причини, яку наводять коментарі вaggregate.yaml. - Рядок
Pull completeозначає, що імпорт отримує те, від чого залежить чернетка сутності Release, як це робитьaggrega pull, уrelease.lock, щоб чернетки одразу проходили валідацію та збірку. З--offlineімпорт нічого не завантажує і називає командуaggrega pull, яку слід виконати.
Що він записує
Сутності Aggregate, Release і Manifest отримують назву imported/supportagent за полем name агента, SupportAgent, скороченим до supportagent — його displayName не читається — у просторі імен, який задає налаштування target_namespace імпортера, тобто imported, якщо ви не задасте інший (Налаштування).
aggregate.yaml — агент, з’єднаний зі своєю моделлю, з ключем, який він пред’являє, оголошеним на з’єднанні, і сама модель:
# 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"Сервер MCP не є ні сутністю Component, ні з’єднанням агента: Agent Framework надсилає його постачальнику моделі як розміщений інструмент, і саме постачальник, а не застосунок, звертається до нього за його url, тому ця адреса має бути досяжною з боку постачальника. Інструкції, параметри запитів до моделі, а також опис, режим схвалення та дозволені інструменти сервера залишаються в декларативному агенті, який читає застосунок; коментарі називають кожен із цих пунктів. API OpenAI — це розміщений сервіс, тому сутність Component агента відхиляє з’єднання з ним, яке не несе жодних облікових даних; з’єднання оголошує їх під ключем OPENAI_API_KEY — змінною, з якої декларативний агент читає свій ключ.
release.yaml — середовище, образ, опублікований порт і джерело ключа:
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: {}Середовище, development, — це типове значення, яке записує імпорт, бо жоден декларативний агент не називає середовища; змініть його, якщо сутність Release розгортається деінде. Образ — це відповідь, яку імпорт прочитав із import-answers.yaml. Агента опубліковано на loopback-адресі вашої машини, на порту 8000, з переспрямуванням на порт, який слухає його програма, infra.port, типово 8000. Ключ — це посилання на змінну ${OPENAI_API_KEY}, назване за змінною, яку читає декларативний агент, і ніколи не значення. Адресу сервера MCP записано так, як її зазначає декларативний агент, для перевірки, і більше ніде не задано: Agent Framework передає її постачальнику у своєму запиті до моделі.
manifest.yaml — сутність Recipe для Compose агента й моделі та реалізація, яка записує посилання на змінну ключа у файл Compose як є:
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 фіксує за дайджестом сутності каталогу, до яких розв’язалася сутність Release, а .aggrega-import.json — це відомості про те, що записав імпорт; їх читає пізніший aggrega import --sync.
Перевірка та збирання
aggrega validate --release release.yamlaggrega build --release release.yaml

Перевірка виводить:
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)і збірка, де <workspace> позначає теку, у якій ви її запустили:
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Рядок notice має рекомендаційний характер: секретна сутність Feature приймає свій origin із values сутності Aggregate або з infra сутності Release, і повідомлення сповіщає, що один листок оголошено в обох. Воно не змінює жодного вердикту.
Сервіс агента в 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Застосунок отримує адресу моделі, її назву та ключ у змінних, які читають клієнти OpenAI з Agent Framework, тож =Env.OPENAI_API_KEY декларативного агента читає ключ, який приєднала сутність Release, там, де застосунок завантажує агента так, як описано в розділі Проєкт. Жодна змінна не містить адреси сервера MCP, до якого звертається постачальник. Модель не отримує власного сервісу: агент звертається до API OpenAI за власною адресою цього API. Ключ — це посилання на змінну, яке заповнюється з вашої оболонки під час запуску стеку. Сервіс публікує свій порт лише на 127.0.0.1.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте в нього цей промпт.
Використовуй лише інструменти Aggrega і не створюй жодної теки самостійно. Якщо тека Workspace ще не містить теки `import-agent-framework`, один раз виклич інструмент `scaffold` зі значенням `example`, встановленим на `import-agent-framework`, і без `dir`: він записує приклад у нову теку `import-agent-framework`, тека `source` якої містить те, що імпортує ця сторінка. Потім виклич інструмент `import` з `workspace_root`, встановленим на `import-agent-framework/source`, `source`, встановленим на `support-agent.yaml`, і `target`, встановленим на `compose`: він читає потрібні відповіді з `import-answers.yaml` поруч із `support-agent.yaml`, записує свої чернетки в `import-agent-framework/source` і завантажує те, що їм потрібно. Потім виклич інструмент `validate` з `workspace_root`, встановленим на `import-agent-framework/source`, і `release`, встановленим на `release.yaml`, та інструмент `build` з `workspace_root`, встановленим на `import-agent-framework/source`, `release`, встановленим на `release.yaml`, і `write`, встановленим на true. Скажи мені, які файли записала збірка; вони лежать у `import-agent-framework/source/dist/`.Відкриття у VS Code
Коли розширення Aggrega для Visual Studio Code встановлено, відкрийте у VS Code теку import-agent-framework/source, куди імпорт записав свої чернетки. Тека містить одну сутність Release, чернетку release.yaml, тож редактор сам вибирає її і під час редагування перевіряє чернетки щодо цієї сутності Release, позначаючи знайдене у файлі та на панелі «Проблеми». Aggrega: Show topology graph у палітрі команд малює компоненти сутності Release і зв’язки між ними. Aggrega: Build, Aggrega: Preview build і Aggrega: Pull діють на ту саму сутність Release, і кожна з них також є кнопкою на панелі Commands подання Aggrega на панелі дій; Build записує свої файли в dist/ теки. Решту описує Використання Aggrega у Visual Studio Code.
Запуск
Ви збираєте образ із проєкту за допомогою власного Dockerfile: код застосунку зі встановленим Agent Framework і декларативним агентом усередині. Docker Compose запускає власну команду образу як сервіс агента, оскільки сутність Recipe не задає жодної, тож ця команда має працювати безперервно і має обслуговувати запити, якщо ви хочете звертатися до агента. Адресу, маршрут і відповідь визначає ваша програма.
Наведений нижче запуск використовував такий образ: Python із пакетами agent-framework-core, agent-framework-openai і agent-framework-declarative з Agent Framework, середовище виконання .NET — образ задав DOTNET_ROOT як його каталог і DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 — support-agent.yaml і, як команду образу, невеликий власний HTTP-сервер програми на порту 8000. Сервер завантажує декларативного агента з AgentFactory(safe_mode=False), тож його =Env.OPENAI_API_KEY читає ключ, який доставляє збірка, і запускає агента один раз для кожного POST /ask. Зберіть свій образ у корені проєкту, запишіть його назву замість ghcr.io/example/support-agent:1.0.0 у import-answers.yaml і знову виконайте імпорт із --sync, який записує нову відповідь у чернетки й знову виконує pull; потім виконайте збірку:
docker build -t docs-assistant:local .aggrega import support-agent.yaml --syncaggrega build --release release.yamlІз відповіддю docs-assistant:local синхронізація серед рядків, які вона виводить, називає одне значення, яке вона змінила:
changed spec.components.supportagent.infra.image in release.yamlПотім встановіть ключ у своїй оболонці й запустіть стек:
export OPENAI_API_KEY='your OpenAI key'docker compose -p docs-assistant -f dist/compose/docker-compose.yaml up -d --wait-p задає назву проєкту, як пояснює крок запуску в розділі Як виконується імпорт.
Тестування
Наведений нижче запит досягає програми, яку запускає образ із цього покрокового посібника: декларативного агента за невеликим HTTP-сервером на порту 8000, що відповідає на POST /ask. Ваша власна програма сама визначає свій маршрут і відповідь. Надішліть його на http://127.0.0.1:8000, адресу, яку публікує published_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]"}Під час запуску OPENAI_API_KEY було встановлено на значення-заповнювач, тож відповідь — це відмова OpenAI, яку передала програма. Ключ, який відхилила OpenAI, — це саме той заповнювач, показаний у замаскованому вигляді, отже =Env.OPENAI_API_KEY декларативного агента прочитав його із середовища, яке надає збірка.
Зупиніть стек командою:
docker compose -p docs-assistant -f dist/compose/docker-compose.yaml downУ Kubernetes імпортуйте з --target helm і надішліть образ до реєстру, з якого ваш кластер завантажує образи, указавши його в import-answers.yaml. Потім створіть Secret openai-api-key і застосуйте збірку, як описує крок запуску в розділі Як виконується імпорт. Deployment агента не має Service, тож перенаправте на нього локальний порт. Команда працює, доки ви її не зупините:
kubectl port-forward deploy/supportagent 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000З іншого термінала надішліть той самий запит на перенаправлений порт:
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]"}