第3章 Prompt エージェントと Hosted エージェントの実行方式を理解する
本章は初稿です。
3.1 この章で学ぶこと
第2章で整理したプロジェクト、モデル、Agent、Conversation、Response を使い、Prompt エージェントと Hosted エージェントの準備・実施手順を比較します。Prompt エージェントは宣言的な定義、Hosted エージェントは独自コードの配備が開発の中心です。どちらでも、利用者の閲覧範囲や入力検証、必要な承認、停止条件を設計する責任は残ります。
本章の目標は、作成するもの、Foundry に任せるもの、自分で実行するものを分け、準備完了・版の配備・応答の成功を別々に確認できることです。Azure の配備・SDK 結合・疎通は未実施であり、この説明を検証済みハンズオンとは扱いません。
図3-1 定義を使うか、コードを配備するか。 矢印は準備から確認までの順序です。Prompt エージェントの独自関数はアプリ側で実行し、Hosted エージェントも版の作成要求だけで配備成功とは判断しません。基盤を管理してもらうことと、実行する処理の安全性が保証されることは別です。[^quickstart][^function-calling][^hosted][^hosted-quickstart]
3.2 Prompt エージェント：モデル、指示、ツールを定義して実行する
Prompt エージェント（プロンプトエージェント）は、利用するモデル、指示、ツールなどを宣言的に定義する方式です。自分でエージェント用コンテナーやサーバーを配備するところから始めずに、役割と入出力を学べます。本教材の基本実習は、この方式を使います。[^quickstart][^runtime]
3.2.1 準備するもの
| 準備するもの | 確認する内容 |
|---|---|
| プロジェクトとモデル | 利用してよいプロジェクトのエンドポイントと、テキスト・function calling など必要な機能に対応するモデルのデプロイ |
| 呼び出す主体と権限 | 作成・編集には Foundry User など、呼び出しだけなら Foundry Agent Consumer など、対象操作に合うロール |
| Agent の定義 | 自分専用の名前、モデルのデプロイ名、役割や制約を記した指示、必要になった段階で追加するツール定義 |
| クライアント | ポータル、または Agent を作成して会話・応答を呼び出すアプリ。Python の場合は対応する SDK と認証パッケージ |
| トレース | Application Insights のプロジェクト接続と、クラウドのトレースを閲覧する権限 |
| 関数の実装 | 独自の function calling を使う場合、要求を検証して関数を実行し、結果を返す処理 |
参照した Python の公式手順は、azure-ai-projects>=2.3.0 と azure-identity を利用します。また、現行クイックスタートは Application Insights の接続とトレース閲覧の準備を求めています。これは、この学習経路の準備条件として扱います。[^quickstart][^resources] Azure 資源や SDK の準備は第5章で具体化します。
権限は操作に応じて分けます。Agent を呼び出せることは、Agent の編集、モデルの新規デプロイ、接続先の RBAC 変更まで許可されていることを意味しません。[^agent-environment]
3.2.2 作成から呼び出しまでの流れ
- 接続先とモデルを確認する。 プロジェクトのエンドポイント、実際の認証主体、利用するデプロイ名を準備表へ記録します。閉域環境なら、実行端末から到達できる経路も先に確認します。
- 最小の指示を作る。 IT 支援という役割、不足情報を確認すること、根拠のない会社固有の設定を断定しないことを定めます。最初は検索ツールを付けず、質問への応答だけを確認します。
- Agent の版を作る。 ポータルで定義するか、Python なら
AIProjectClient.agents.create_versionとPromptAgentDefinitionを使い、モデルと指示を登録します。返された Agent 名と版を記録します。[^quickstart] - Agent に結び付いたクライアントを用意する。 現行の Python 例では
project.get_openai_client(agent_name=...)を使います。名前だけの参照を、作成した版への厳密な固定と同一視しません。学習中は同名 Agent を他の処理で更新せず、利用する版を追えるようにします。[^quickstart] - 会話を作って応答を呼び出す。 相談ごとの Conversation を作り、その ID と入力を
responses.createへ渡します。応答の状態、文章、ツール要求などの出力種類を確認します。[^runtime] - 検索を必要な段階で追加する。
search_knowledgeの関数定義を追加し、呼び出し要求が返ったら、実行側で関数名、引数、利用者の閲覧範囲、呼び出し上限を検証します。実行結果を要求の ID と対応付けて返し、回答・確認質問・中断へ進みます。[^function-calling] - 結果と費用を観察する。 文章が返ったことと、期待する振る舞いを満たしたことを分けます。応答の ID、利用した版、モデル利用量、実行経路を対応付け、不要な会話や版を後で整理します。
最小の接続コードは第7章、関数の要求と実行の往復は第10章で扱います。この段階で大切なのは、Prompt エージェントに関数の仕様を登録しても、手元の Python 関数が Foundry 内で自動実行されるわけではないという責任分界です。[^function-calling]
3.3 Hosted エージェント：自分のコードを Foundry の実行基盤へ配備する
Hosted エージェント（ホスティッドエージェント）は、自分のコードで処理の組み立てや状態管理を行い、Foundry の管理する実行基盤で動かす方式です。フレームワークや独自の制御を持ち込みたい場合の発展先ですが、Hosted エージェントを選ぶだけで自律性や業務上の安全性が高くなるわけではありません。[^hosted]
3.3.1 準備するものと、二つの配備方法
実行時はコンテナーを使いますが、配備の入口は、ビルド済みイメージの持ち込みだけではありません。 現行クイックスタートには、ソースコードを ZIP でアップロードし、Foundry が依存関係の解決とリモートビルドを行う方式があります。Dockerfile の作成、ローカル Docker でのビルド、ACR への手動 push を、すべての Hosted エージェントの実習で必須とは扱いません。[^hosted][^hosted-quickstart]
| 配備方法 | 自分で用意するもの | 配備の流れ |
|---|---|---|
| ソースコード配備 | Agent のコード、依存関係定義、実行ランタイム、起動するファイルやコマンド、Agent の構成 | コードをパッケージ化して送信し、Foundry 側で依存関係を解決・ビルドする |
| イメージ持ち込み | コードと依存関係を含むコンテナーイメージ、レジストリの参照、取得に必要な接続と権限、Agent の構成 | 自分でビルドしたイメージを ACR へ配置し、Foundry へ版を登録する |
コード配備でも、ランタイムの種類、依存パッケージ、起動方法を決める責任は残ります。また、ビルドや成果物管理が手順の中で隠れることと、関連資源や費用が一切ないことは同じではありません。選んだ配備手順で、何が作成・再利用されるかを確認します。[^hosted-quickstart][^registry-pricing]
共通して準備するのは、次の項目です。
| 準備するもの | 確認する内容 |
|---|---|
| プロジェクトと推論先 | 本教材の題材では、利用可能な Foundry プロジェクトとモデルのデプロイ |
| 開発・配備用ツール | 選んだ手順に対応する Azure Developer CLI（azd）と拡張、または Azure AI Projects SDK。実行コードのフレームワーク依存とは別に確認する |
| Agent のコード | モデルやツールの呼び出し、入力検証、状態の扱い、終了条件を実装した処理 |
| 受付プロトコル | Responses など、クライアントとコンテナーの間の契約。対応ライブラリやアダプターもそろえる |
| 版の構成 | コードまたはイメージ、CPU・メモリ、起動設定、プロトコル、必要な非秘密の設定値 |
| 接続・認証・認可 | 配備する人、プロジェクトの managed identity、Agent の実行時 ID が、それぞれ必要とする権限 |
| 観測と終了後の整理 | Application Insights とトレース閲覧権限、確認するログ、保持する版、片付ける資源、費用の負担先 |
公式 Hosted エージェントのクイックスタートは、既存プロジェクトの場合にプロジェクト範囲の Foundry Project Manager、新規プロジェクトの資源準備ではリソースグループ範囲の Owner を前提とします。これはその手順の要件であり、「Foundry を使う人は全員 Owner」という意味ではありません。Azure 資源の作成、ロール割り当て、Agent の操作にはそれぞれ別の権限が関わります。[^hosted-quickstart][^hosted-permissions]
参照した Python によるコード配備の公式例は Python 3.13 以上と azure-ai-projects>=2.3.0 を使います。C# のコード配備 API は、参照した手順では prerelease のパッケージが必要です。Prompt エージェントと Hosted エージェント、配備用 SDK と実行コードの SDK が、すべて同じ条件で動くとは考えません。[^hosted-quickstart]
3.3.2 コード配備を中心に、実施の流れを追う
入門では、Responses に対応した公式サンプルを入口にすると、会話の題材を継続できます。Azure Developer CLI を使う経路は、テンプレートの初期化、資源の準備、ローカル確認、配備、リモート呼び出しをつなぎます。Python SDK の経路は、既存のプロジェクトとモデルを使って Agent の版を作るもので、プロジェクトやモデルを一式作る経路とは異なります。[^hosted-quickstart]
- サンプルと対象プロジェクトを選ぶ。 自分専用の作業場所へ初期化し、作成する Agent 名と使用するモデルを決めます。既存プロジェクトを選んだだけではテンプレートのモデル設定が自動で目的のデプロイに変わるとは限らないため、既存のデプロイを使う指定と配備定義を確認します。[^hosted-quickstart]
- コードと受付プロトコルを用意する。 IT 支援の指示、モデルの呼び出し、必要なツール実行を実装します。Responses の対応ライブラリやアダプターで、HTTP の受付、ヘルスチェック、トレース連携の契約を満たします。任意の HTTP サーバーが起動しただけで Hosted エージェントの契約を満たすとは扱いません。[^hosted]
- 配備条件を確認する。 ソースの場所、依存関係、ランタイム、起動方法、CPU・メモリ、プロトコル、モデルのデプロイ名をそろえます。公式サンプルの
azure.yamlにはhost: azure.ai.agent、kind: hostedと、コード配備や資源の構成が記載されています。[^hosted-template] サンプルの環境変数名は第5章の基本課題と異なる場合があるため、起動するコードが読む名前と、配備側で設定する値を対応付けます。 - 必要な資源と接続を準備する。 作成・再利用する Foundry 資源、モデル、Application Insights、必要なレジストリなどを確認します。既存プロジェクトでも、配備定義によってモデルなどの追加資源を作る場合があるため、変更対象と費用を確認してから進めます。[^hosted-quickstart]
- 手元で起動を確認する。 依存関係と起動設定が合い、選んだプロトコルで入力を受けられるかを確かめます。実際に Foundry モデルを呼ぶローカル確認は、モデルの利用料が発生し得ます。
- コードまたはイメージから版を配備する。 コード配備では必要なファイルだけを ZIP にまとめ、リモートビルドを使います。Python の公式例は
agents.create_version_from_codeとHostedAgentDefinition、CodeConfigurationを使います。イメージ方式なら、配備するイメージの参照と取得権限をそろえます。[^hosted-quickstart][^hosted] - 版の準備完了と呼び出し先を確認する。 作成要求を受け付けたことだけで成功とはせず、版の状態が
activeになることを確認します。failedや待機上限を超えた場合は中断し、診断情報を調べます。その後、Agent のエンドポイントが意図した版を扱う設定になっていることを確認します。[^hosted-quickstart] - リモートで呼び、実行経路を確認する。 Agent に結び付いたクライアントから相談を送信し、回答、モデル呼び出し、ツール、失敗経路をトレースで追います。配備できたことと、業務上期待する結果になったことを分けて判断します。
コードのアップロードには、資格情報、.env、仮想環境、不要なキャッシュなどを含めません。モデル名や接続先などの非秘密の設定と、秘密情報を分けます。イメージへ秘密情報を焼き込むことや、共有資格情報を設定値へ直書きすることも避け、対応する ID と秘密情報管理を使います。[^hosted-quickstart][^hosted]
アップロード可能なセッションの $HOME と、信頼するアプリのコード・設定・指示ファイルも分離します。添付ファイルを受け付ける場所からコードや設定を自動で読み込むと、アップロードした人が Agent の動作を変えられる可能性があります。Python の公式例は PYTHONNOUSERSITE=1 で起動時の user-site パッケージの読み込みを無効にしますが、この設定だけで、アップロード先からのすべての読み込みを防ぐわけではありません。[^hosted][^hosted-quickstart]
Python の公式クイックスタートの配備例は、最後に以前のエンドポイント設定を復元し、作成した一時的な版を削除する構成です。呼び出しを試すサンプルと、使い続ける配備は区別します。 継続利用では、保持する版とルーティング、不要になった版の整理を明示的に管理し、サンプルの後処理を読まずに「永続的な配備が残った」と判断しません。[^hosted-quickstart]
3.3.3 実行中に Foundry が管理するものと、自分が管理するもの
Hosted エージェントは、一つの大きな共通コンテナーを固定台数で動かすという捉え方ではなく、論理セッションごとに VM で分離された sandbox を用意する実行モデルです。CPU・メモリの指定はセッションあたりの割り当てです。現行のモデルでは、従来型の replica 数や warm pool の台数を設定する方式ではありません。[^hosted]
セッションは要求に応じて動き、要求が来るたびに idle timeout のタイマーを更新します。参照した説明では、タイムアウトは 2〜240 分、既定は 15 分です。時間を超えると計算資源を解放し、再開時には $HOME や /files の内容を復元します。コンテナー内の変数だけを、再起動後も残る業務状態として扱いません。[^hosted]
Conversation は相談の履歴、セッションは計算資源とファイルなどの実行状態です。計算資源が解放されても、Conversation の履歴は独立して保持されます。さらに、アプリケーションの状態を保存する durable な key-value の state store もあります。これらは、第2章 2.2.3節で説明した Foundry Memory の長期記憶機能と同じものではありません。[^hosted]
| 管理する対象 | Foundry に任せる部分 | 自分が決める部分 |
|---|---|---|
| 実行基盤 | セッションの計算資源、分離、idle 後の解放と再開 | CPU・メモリ、idle timeout、必要な同時利用量を踏まえた設計 |
| 受付と会話 | 宣言したプロトコルのエンドポイント、Responses での会話管理 | プロトコルへの対応、利用者と会話の対応、独自の業務状態 |
| Agent の版 | コード・資源・設定を含む版の管理 | 何を配備し、どの版をエンドポイントで使うか |
| 認証とアクセス | 専用の Agent ID と基盤の認証機構 | 外部資源の権限、ユーザーの閲覧範囲、必要な承認 |
| 観測と安全な終了 | 対応するトレースや実行基盤のライフサイクル | 記録する情報、入力検証、呼び出し上限、拒否や失敗時の停止 |
Responses は、会話の履歴、ストリーミング、応答のライフサイクルをプラットフォームへ任せる経路です。Invocations は任意の JSON や独自のイベント配信に向きますが、会話履歴などの管理を自分で設計する範囲が広がります。音声の双方向ストリーミングには Invocations の WebSocket など別の契約があります。本教材のテキスト相談では Responses を出発点にします。[^hosted]
ID も分けて考えます。プロジェクトの managed identity は、たとえば ACR からイメージを取得する基盤側の処理に使います。Agent 専用の実行時 ID は、コードからモデル、ツール、接続先を呼ぶために使います。既定のモデル推論・セッション保存のアクセスと、独自の Azure 資源へ付与する権限は別です。ユーザーの権限を委任する場合も、Hosted エージェントの実行時 ID がなくなるわけではありません。[^hosted][^hosted-permissions]
版はコード、資源、設定、プロトコルを含む変更不能のスナップショットです。変更したい場合は新しい版を作ります。現行の専用エンドポイントは一つの版へ 100% の要求を送るため、複数の版へ割合で分配できると推測して構成しません。[^hosted]
ネットワークも採用条件を確認します。現行 Hosted エージェントの説明には、ネットワーク分離された Foundry 資源や、顧客 VNet への送信を使う構成があります。長期記憶の VNet 制約を Hosted エージェント全体へ広げて「Hosted エージェントは VNet 非対応」と判断しません。私設レジストリなどにはプロジェクトの作成時期による条件もあるため、第6章と公式資料を対応付けて確認します。[^hosted]
3.4 小さな実習：同じ題材で準備表を作る
続けて、基本課題を Prompt エージェントで行う場合と、同じ題材を Hosted エージェントのコード配備へ発展させる場合を紙上で比較します。Azure 資源を作成する実習ではありません。
| 記録すること | Prompt エージェントの基本課題 | Hosted エージェントのコード配備 |
|---|---|---|
| Foundry の接続先と推論先 | プロジェクトとモデルのデプロイ | 同じ項目に加え、配備対象の Agent と版 |
| 自分で用意する処理 | クライアントと、追加する検索関数の実行 | Agent のコード、依存関係、受付プロトコル、配備設定 |
| 追加のサービス | ローカル検索だけなら自分の Search は不要。トレースは公式手順に沿って準備する | 観測、外部接続、成果物管理など、選んだ配備方式で必要なもの |
| 費用として数える量 | モデル利用量、採用する連携先や保存・観測 | 左の項目に加え、稼働セッションの CPU・メモリ時間 |
| 終了後の整理 | 保持する版・会話と、削除を許可された対象 | 左の項目に加え、セッションや配備成果物など |
表の各項目について「どこで確認するか」「誰が準備するか」を補います。まだ実接続していないものを、準備済み・検証済みとして記録しません。
費用を記録するときは、第4章のメーターと対応付けてください。トレースの準備や確認先を書いたことは、実際の接続を確認した証拠にはなりません。
3.5 確認課題
次の判断を、自分の準備表と照合して説明してください。正常な応答だけでなく、権限不足、関数の検証失敗、版の状態が failed、待機上限超過のときにどこで止めるかも補います。
| 問い | 判断の要点 |
|---|---|
| Prompt エージェントに関数の定義を登録すれば、手元の関数は Foundry が実行するか | 独自の function calling には、実行側の処理と検証が必要 |
| Hosted エージェントは必ず自分で Dockerfile を作り、ACR へ手動 push するか | ソースコード配備とイメージ持ち込みを区別する |
| Hosted エージェントの版の作成要求が成功すれば、利用開始を確認したことになるか | 準備完了の状態、エンドポイントが扱う版、実際の入出力を別に確認する |
3.6 まとめ
Prompt エージェントはモデル・指示・ツールを定義し、独自関数の検証と実行はアプリ側に残ります。Hosted エージェントはコード・起動条件・プロトコルをそろえ、コードまたはイメージから版を配備します。
実行基盤、会話履歴、セッションのファイルと業務状態、長期記憶を混同しません。版の準備完了、呼び出す版、権限、観測、終了後の整理を確認し、続く第4章で各方式の利用量を積算します。
3.7 参考情報
- Quickstart: Create a prompt agent — Prompt エージェントの準備、定義の作成、会話と応答の呼び出し
- Use function calling with Microsoft Foundry agents — 独自関数の定義、実行要求、結果返却の責任分界
- Hosted agents in Foundry Agent Service — セッション、版、ID、プロトコルとネットワークの概念
- Quickstart: Deploy your first hosted agent — SDK や配備方法別の前提条件と実施手順
- Hosted agent permissions reference — 配備用の主体と実行時の主体に必要な権限
[^runtime]: Build with runtime components in Foundry Agent Service — Microsoft
[^function-calling]: Use function calling with Microsoft Foundry agents — Microsoft
[^quickstart]: Quickstart: Create a prompt agent — Microsoft
[^agent-environment]: Set up your environment for Foundry Agent Service — Microsoft
[^resources]: Quickstart: Set up Microsoft Foundry resources — Microsoft
[^hosted]: Hosted agents in Foundry Agent Service — Microsoft
[^hosted-quickstart]: Quickstart: Deploy your first hosted agent — Microsoft
[^hosted-permissions]: Hosted agent permissions reference — Microsoft
[^hosted-template]: Agent Framework basic Responses sample: azure.yaml — Microsoft
[^registry-pricing]: Azure Container Registry pricing — Microsoft
前章：第2章 Microsoft Foundry の全体像をつかむ · 教材の目次へ戻る · 次章：第4章 Microsoft Foundry の課金と予算を整理する