コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

Microsoft Agent Framework の宣言型エージェントをインポートする

このウォークスルーでは、Microsoft Agent Framework の宣言型エージェント(MCP サーバーを通じて検索したドキュメントから質問に答えるアシスタント)をインポートし、アプリケーションを Docker Compose 向けにビルドします。インポートは、ビルドが読み取るすべてのファイルをドラフトします。エージェントとそのモデル、エージェントがモデルに提示するキーを表す変数参照、そしてそれぞれの実現です。どの宣言型エージェントも保持していない唯一の値、つまりアプリケーションを実行するイメージについて、一度だけ尋ねます。以下のすべてのファイルと出力ブロックは実際の実行から得たものです。宣言型エージェントとウォークスルーの各段階は import-agent-framework の例にあり、そこではチェックスクリプトがインポートを再実行し、書き出した内容、出力した内容、このページが引用するブロックを、そこに保存されているファイルと比較し、インポートが書き出したものを検証してビルドします。

サンプルを生成する

このインポートは、このページのコマンドで実行することも、AI アシスタントに実行させることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

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

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。それに続く以下のコマンドは、新しいフォルダーの source フォルダーに移動します。このフォルダーには、このページがインポートするものが入っており、インポートはここで実行します:

Terminal window
cd import-agent-framework

Visual Studio Code で開いた、生成された例の source フォルダー。OpenAI モデルと Microsoft Learn MCP ツールを持つプロンプトエージェント SupportAgent が表示されています。

プロジェクト

Agent Framework 上に構築されたアプリケーションは、宣言型エージェントからエージェントを読み込めます。宣言型エージェントとは、エージェントのモデル、指示、ツールを指定する kind Prompt の YAML ドキュメントです。このウォークスルーのために書かれたこのエージェントは、OpenAI の gpt-4.1-mini と、Microsoft Learn が公開している MCP サーバーを指定しています:

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 からこの式を読み取るのは、アプリケーションが Agent Framework 自身のセキュリティ設定である AgentFactory(safe_mode=False) で宣言型エージェントを読み込み、かつ .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

インポートはカタログの Agent Framework エージェントと OpenAI モデルの Components を参照し、--target はカタログの Recipes から Manifest をドラフトします。ワークスペースはカタログフォルダーを指定していないため、インポートは、インポーターの取得元と同じレジストリから標準ライブラリカタログを読み取ります。これは公開済みカタログの署名付きスナップショットで、最初のインポートが取得し、検証してワークスペースのコンテンツキャッシュに保持し、インポートがドラフトの隣に書き込む記録の中でそのダイジェストによって示されます。独自のカタログフォルダーを — 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.
>

そして回答をドラフトと、support-agent.yaml の隣にある import-answers.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"

2 つ目の回答は、--target helm による Kubernetes 向けビルドのためのものです。その場合、エージェントは OpenAI のキーを Kubernetes の Secret から読み取り、回答はキーそのものではなく 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 の出力にはエージェントとそのモデルのマッピング方法と書き込まれたファイルが一覧表示され、通知にはインポートが agent-framework として認識され 3 つのファイルをドラフトしたことが示されています。

  • 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 でサーバーに到達します。そのため、このアドレスはプロバイダーから到達可能でなければなりません。指示、モデルへのリクエストのオプション、およびサーバーの説明、承認モード、許可されたツールは、アプリケーションが読み取る宣言型エージェント内にとどまります。コメントがそれぞれを示しています。OpenAI の API はホスト型サービスであるため、エージェントの Component は資格情報を持たない、そこへの接続を拒否します。接続は、宣言型エージェントがキーを読み取る変数である OPENAI_API_KEY というキーの下に、資格情報を 1 つ宣言しています。

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 から読み取った回答です。エージェントはマシンのループバックアドレスのポート 8000 で公開され、そのプログラムが待ち受けるポート infra.port(設定しなければ 8000)に転送されます。キーは変数参照 ${OPENAI_API_KEY} で、宣言型エージェントが読み取る変数にちなんで名付けられており、値になることはありません。MCP サーバーのアドレスは、レビューのために宣言型エージェントが記述しているとおりに書かれ、ほかのどこでも設定されません。Agent Framework は、モデルへのリクエストの中でそれをプロバイダーに渡します。

manifest.yaml — エージェントとモデルの Compose Recipe、およびキーの変数参照を書かれたとおりに 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 を Aggregate の values または Release の infra から受け付け、この通知は 1 つのリーフが両方で宣言されていることを報告しています。判定は何も変わりません。

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

アプリケーションは、Agent Framework の OpenAI クライアントが読み取る変数でモデルのアドレス、名前、キーを受け取ります。そのため、宣言型エージェントの =Env.OPENAI_API_KEY は、アプリケーションがプロジェクトで説明したとおりにエージェントを読み込む場合に、Release がアタッチしたキーを読み取ります。MCP サーバーのアドレスを運ぶ変数はなく、このサーバーにはプロバイダーが到達します。モデルには独自のサービスは作られず、エージェントは OpenAI API にその API 自身のアドレスで到達します。キーは変数参照であり、スタックの起動時にシェルから埋められます。サービスはポートを 127.0.0.1 でのみ公開します。

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。Workspace フォルダーにまだ `import-agent-framework` フォルダーがない場合は、`example` を `import-agent-framework` に設定し、`dir` を指定せずに、`scaffold` ツールを 1 回呼び出してください。これは例を新しい `import-agent-framework` フォルダーに書き込み、その `source` フォルダーにこのページでインポートするものが入ります。次に、`workspace_root` を `import-agent-framework/source`、`source` を `support-agent.yaml`、`target` を `compose` に設定して `import` ツールを呼び出してください。これは必要な回答を `support-agent.yaml` の隣にある `import-answers.yaml` から読み取り、下書きを `import-agent-framework/source` に書き込み、下書きが必要とするものをプルします。次に、`workspace_root` を `import-agent-framework/source`、`release` を `release.yaml` に設定して `validate` ツールを呼び出し、`workspace_root` を `import-agent-framework/source`、`release` を `release.yaml`、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。それらは `import-agent-framework/source/dist/` の下にあります。

VS Code で開く

Visual Studio Code 用の Aggrega 拡張機能をインストールした状態で、インポートが下書きを書き込んだフォルダー import-agent-framework/source を VS Code で開きます。このフォルダーには Release が 1 つ、下書きの release.yaml だけがあるため、エディターがそれを自動的に選択し、下書きを編集するたびにその Release に照らしてチェックし、見つけたものをファイル内と「問題」パネルに表示します。コマンドパレットの Aggrega: Show topology graph は、Release のコンポーネントとそれらの間の接続を描画します。Aggrega: Build、Aggrega: Preview build、Aggrega: Pull は同じ Release に対して動作し、それぞれアクティビティバーの Aggrega ビューにある Commands パネルのボタンでもあります。Build はファイルをフォルダーの dist/ に書き込みます。その他については Visual Studio Code で Aggrega を使う を参照してください。

実行する

イメージは、独自の Dockerfile を使ってプロジェクトからビルドします。中身は、Agent Framework がインストールされ、宣言型エージェントを含むアプリケーションのコードです。Recipe はコマンドを設定しないため、Docker Compose はイメージ自身のコマンドをエージェントのサービスとして実行します。したがって、そのコマンドは実行し続ける必要があり、エージェントに到達したい場合はリクエストを処理する必要があります。アドレス、ルート、応答はプログラムが決定します。

以下の実行では、そのようなイメージを使用しました。Agent Framework の agent-framework-core、agent-framework-openai、agent-framework-declarative パッケージを備えた Python、.NET ランタイム(イメージは DOTNET_ROOT をそのディレクトリに設定し、DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 を設定しました)、support-agent.yaml、そしてイメージのコマンドとして、ポート 8000 で動作するプログラム独自の小さな HTTP サーバーです。サーバーは AgentFactory(safe_mode=False) で宣言型エージェントを読み込むため、その =Env.OPENAI_API_KEY はビルドが渡すキーを読み取ります。また、POST /ask ごとにエージェントを 1 回実行します。プロジェクトのルートでイメージをビルドし、import-answers.yaml の ghcr.io/example/support-agent:1.0.0 をその名前に書き換え、--sync を付けて再度インポートします。これにより新しい回答が下書きに書き込まれ、再度プルされます。その後ビルドします:

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

回答を docs-assistant:local にすると、同期は出力する行の中で、変更した 1 つの値を示します:

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 はプロジェクトに名前を付けます。インポートの実行方法 の実行ステップで説明しているとおりです。

テストする

以下のリクエストは、このウォークスルーのイメージが実行するプログラムに届きます。ポート 8000 の小さな HTTP サーバーの背後にある宣言型エージェントで、POST /ask に応答します。独自のプログラムでは、ルートと応答はそのプログラム自身が決めます。プログラムが待ち受けを始めたら、つまりスタックの起動から数秒後に、published_port が公開するアドレス http://127.0.0.1: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]"}

この実行では 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]"}