Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Импорт декларативного агента Microsoft Agent Framework

В этом пошаговом примере импортируется декларативный агент Microsoft Agent Framework — ассистент, отвечающий на вопросы по документации, которую он ищет через сервер MCP, — и приложение собирается для Docker Compose. Импорт создаёт черновик каждого файла, который читает сборка: агента и его модель, ключ, который агент предъявляет модели, в виде ссылки на переменную, и реализации каждого из них. Он один раз запрашивает единственное значение, которого не содержит ни один декларативный агент, — образ, в котором работает ваше приложение. Каждый файл и каждый блок вывода ниже взяты из реального запуска; декларативный агент и каждый этап примера находятся в примере import-agent-framework, где скрипт проверки снова запускает импорт, сравнивает то, что он записывает, что выводит, и блоки, которые цитирует эта страница, с хранящимися там файлами, а также проверяет и собирает то, что записал импорт.

Создание примера

Этот импорт можно выполнить командами с этой страницы или поручить его вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку; следующая, ниже, переходит в её папку source, которая содержит то, что импортирует эта страница, и в которой выполняется импорт:

Terminal window
cd import-agent-framework

Папка source сгенерированного примера, открытая в Visual Studio Code, с агентом-промптом SupportAgent, его моделью OpenAI и инструментом MCP Microsoft Learn.

Проект

Приложение, построенное на Agent Framework, может загрузить агента из декларативного агента — документа YAML вида Prompt, который называет модель агента, его инструкции и инструменты. Этот агент, написанный для данного примера, называет gpt-4.1-mini от OpenAI и сервер MCP, который публикует Microsoft Learn:

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

Ключ модели записан как =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:

Terminal window
cd source

Запуск импорта

Укажите файл декларативного агента. Импорт читает каждого декларативного агента как отдельный файл и никогда как директорию:

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

В стандартный вывод он выводит список записанного:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .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 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)

Импорт, запущенный из редактора: созданные черновики Aggregate, Release и Manifest появляются рядом с декларативным агентом, вывод Aggrega перечисляет, как были сопоставлены агент и его модель и какие файлы записаны, а уведомление сообщает, что импорт создал 3 файла, распознанных как agent-framework.

  • Строка 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/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"

Сервер MCP не является ни сущностью Component, ни соединением агента: Agent Framework отправляет его поставщику модели как размещённый инструмент, и именно поставщик, а не приложение, обращается к нему по его url, поэтому этот адрес должен быть доступен со стороны поставщика. Инструкции, параметры запросов к модели, а также описание, режим одобрения и разрешённые инструменты сервера остаются в декларативном агенте, который читает приложение; комментарии называют каждый из этих пунктов. API OpenAI — размещённый сервис, поэтому сущность Component агента отклоняет соединение с ним, не несущее никаких учётных данных; соединение объявляет их под ключом OPENAI_API_KEY — переменной, из которой декларативный агент читает свой ключ.

release.yaml — среда, образ, опубликованный порт и источник ключа:

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

Окружение, development, — это значение по умолчанию, которое записывает импорт, потому что ни один декларативный агент не называет окружения; измените его, если сущность Release развёртывается в другом месте. Образ — это ответ, который импорт прочитал из import-answers.yaml. Агент публикуется на loopback-адресе вашей машины, на порту 8000, с перенаправлением на порт, который слушает его программа, infra.port, по умолчанию 8000. Ключ — это ссылка на переменную ${OPENAI_API_KEY}, названная по переменной, которую читает декларативный агент, и никогда не значение. Адрес сервера MCP записан так, как его указывает декларативный агент, для проверки, и больше нигде не задаётся: Agent Framework передаёт его поставщику в своём запросе к модели.

manifest.yaml — сущность Recipe для Compose агента и модели, а также реализация, которая записывает ссылку на переменную ключа в файл Compose как есть:

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 фиксирует по дайджесту сущности каталога, в которые разрешилась сущность Release, а .aggrega-import.json — это сведения о том, что записал импорт; их читает последующий aggrega import --sync.

Проверка и сборка

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

Черновик сущности Release, открытый в редакторе после валидации; вывод Aggrega и уведомление сообщают, что проблем не найдено.

Сборка черновика сущности Release: в Проводнике появляется папка dist, вывод Aggrega перечисляет записанный файл Docker Compose, а уведомление сообщает, что записан 1 файл.

Проверка выводит:

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; затем выполните сборку:

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

С ответом docs-assistant:local синхронизация среди выводимых ею строк называет единственное значение, которое она изменила:

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

Затем задайте ключ в своей оболочке и запустите стек:

Terminal window
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, как только программа начнёт слушать, через несколько секунд после запуска стека:

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

При запуске OPENAI_API_KEY был установлен в значение-заполнитель, поэтому ответ — это отказ OpenAI, переданный программой. Ключ, который отклонила OpenAI, — это и есть тот заполнитель, показанный в замаскированном виде, а значит, =Env.OPENAI_API_KEY декларативного агента прочитал его из окружения, которое предоставляет сборка.

Остановите стек командой:

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

В Kubernetes выполните импорт с --target helm и отправьте образ в реестр, из которого загружает образы ваш кластер, указав его в import-answers.yaml. Затем создайте Secret openai-api-key и примените сборку, как описывает шаг запуска в разделе Как выполняется импорт. У Deployment агента нет Service, поэтому перенаправьте на него локальный порт. Команда работает, пока вы её не остановите:

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

Из другого терминала отправьте тот же запрос на перенаправленный порт:

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