1. はじめに
エージェント開発では、モデル呼び出しとツール呼び出しの調整、作業中のファイル管理、複数段階の処理の継続といった「実行の仕組み」を、多くのチームが似た形で実装しています。Microsoft Foundry Agent Service の Microsoft Copilot harness は、この仕組みを Foundry が運用する形で提供する public preview 機能です。[^harness-announcement]
本稿の目的は、harness でエージェントを作る流れと、作る前に決めておくべき設計判断を一通りまとめることです。最後に、確認できていない点と本番化前のチェックを挙げます。
本文の手順と設定値は公式資料に基づきます。Azure 上での作成・実行は未検証です。preview の仕様は変わりやすいため、実施時に公式資料で再確認してください。
2. Copilot harness とは何か
2.1 位置づけ
Copilot harness は、Prompt エージェントのための任意の管理ランタイムです。Foundry が harness と実行環境を運用するため、harness のコードをデプロイ・保守する必要はありません。リソースは引き続き Prompt エージェントで、アプリケーションは Responses API で呼び出します。[^harness-guide]
harness を選んでも、エージェントの種類や認可の仕組みは変わりません。一方、呼び出し先と実行環境の運用には違いがあります。[^harness-guide]
表1 Copilot harness 選択後の定義・呼び出し・運用
| 観点 | harness を選んだときの扱い |
|---|---|
| エージェントの種類 | Prompt エージェントのまま |
| 定義 | モデル、指示、ツールなど従来のフィールドを設定する |
| 呼び出し | エージェントの Responses エンドポイントを使う |
| ID とガバナンス | Foundry のプロジェクトロール、エージェント ID、接続、ポリシーが引き続き効く |
| 運用 | Foundry が実行環境を運用する(別リソースとしては管理しない) |
2.2 4 つの構成要素
アナウンスでは、public preview の構成要素として次の 4 つが挙げられています。[^harness-announcement]
- 再利用できるスキル: 指示・スクリプト・補助資料を手順としてまとめる
- 接続するツール: 対応する Foundry ツールと MCP ツール。認証と承認は明示的に設定する
- 実行と委任: ファイルやコードを扱い、組み込みのサブエージェントへ範囲を絞って委任する
- ソース管理できるエージェント定義: Foundry 上で作って試す、またはアプリのコードと一緒に定義を管理する
3. 3 つの実行方式の使い分け
エージェントを作る前に、harness が本当に必要かを判断します。公式は次の 3 択を示しています。[^harness-announcement]
表2 Prompt エージェントと Hosted エージェントの選び方
| 選択肢 | 向いている要求 |
|---|---|
| harness なしの Prompt エージェント | 指示と対応ツールだけで足りる |
| harness ありの Prompt エージェント | スキル、管理された実行、ファイル、サブエージェント、複雑なツール連携を、ランタイムを持たずに使いたい |
| Hosted エージェント | フレームワーク、エージェントループ、ミドルウェア、依存関係、実行時の挙動を自分で決めたい |
判断の目安は単純です。「関数を 1 つ呼んで答える」なら harness なし、「手順書に沿ってファイルを読み、複数ツールを連携する」なら harness あり、「ループそのものを自分で制御したい」なら Hosted です。高機能だからという理由で常に harness を選ぶ必要はありません。
4. 作る前に決める 3 つの設計判断
図1 Copilot harness と業務アプリの責任分界
Foundry はモデルと対応ツールの呼び出しを調整し、会話ごとの作業領域と実行環境を管理します。一方、利用者と会話のひも付けや、業務データを閲覧・変更してよいかの判断は、業務アプリ側で行います。図の矢印は Responses API で交わす要求と結果を表し、ネットワーク配置を示すものではありません。[^harness-guide]
独自関数の呼び出し要求が返った場合は、アプリが関数名・引数・利用者の権限を検証し、必要な承認を得てから実行します。その結果を function_call_output として同じ会話に返します。harness が独自関数を代わりに実行するわけではありません。[^harness-guide][^function-calling]
4.1 組み込みツールは必要なものだけ許可する
harness の組み込みツールは File system read・File system write・Shell・Web・Subagents の 5 つで、新規エージェントでは、サービスや組織のポリシーによる制約の下で既定で有効です。第 5 章のテキスト応答の確認にはどれも不要なので、5 つとも無効にし、別途宣言するツールも追加しません。たとえば添付を読む用途に変えるなら、まず File system read だけを有効にします。[^harness-guide]
- Shell を有効にしたまま File system read・File system write・Web を無効にしても、厳密な制限にはなりません。 Shell は実行環境が許可するファイルやネットワークにアクセスできます。別途宣言する Shell や Code Interpreter も、組み込みツールの設定とは独立しています。[^harness-guide]
- 組み込みの Web は URL を指定した取得であり、検索語から情報を探す Foundry の Web search とは別です。[^harness-guide]
4.2 スキルは手順、ツールは能力
スキルは、繰り返し使う手順をまとめた単位です。SKILL.md を入口に、スクリプトや補助資料を含められます。Foundry では版を持つリソースとして管理され、Agent の版には変更不能なスキルの版が保持されます。[^skills-guide][^harness-guide]
「OS を確認する」「資料にない値を補わない」といった手順はスキルに書きます。一方、検索する・ファイルを読む・チケットを登録するといった実行能力はツールで与えます。手順に書いたことは権限の根拠にならず、スキルは第三者のものを無審査で追加せず、内容・送信先・依存関係をレビューします。
4.3 会話・ワークスペース・成果物を区別する
harness は履歴を保持する会話ごとに別のワークスペースを使い、作業ファイルや実行状態をそこに置きます。sandbox の通常のアイドル移行・再開・置き換えを経ても、ワークスペースの状態は維持されます。ただし、sandbox は永続的な出力の保存先ではありません。重要な成果物は Foundry Files などの永続的な保存先へ保管します。[^harness-guide]
また、harness エージェントへの応答要求にはすべて会話が必要です。store は省略するか true を指定します。store: false や previous_response_id は使えません。[^harness-limits]
5. エージェントを作る
5.1 前提条件
確認基準日: 2026-11-20。以降の手順はいずれも、既存の Foundry プロジェクトとモデルデプロイを使い、新しいエージェントを作ります。[^harness-guide]
- プロジェクトとモデル: harness 専用の対応表でリージョンを確認します。推論とツール呼び出しに対応し、そのリージョンの Prompt エージェントで使えるモデルをデプロイしておきます。BYOM は非対応です。[^harness-limits]
- 作成・呼び出しをする ID: 対象プロジェクトのスコープで
Foundry Userロールが必要です。ロール名の変更が反映されていない画面では、旧名のAzure AI Userが表示されることがあります。[^harness-guide][^azd-extensions] - エージェント自身の ID: Toolbox の呼び出しや生成ファイルの返却を追加する場合は、作成後にエージェントの
instance_identity.principal_idにも、同じプロジェクトのスコープでFoundry Userを付与します。今回のテキスト応答だけの確認では、この追加割り当ては不要です。[^harness-guide] - スキル: 後から追加する場合は、エージェントと同じ Foundry プロジェクトで作成します。[^harness-guide][^skills-guide]
5.2 ポータルで作る
公式のポータル手順に沿って、最初の質問を送る前にツール設定を保存します。
- Microsoft Foundry で New Foundry を有効にし、対応リージョンのプロジェクトを選びます。
- Build an agent → Create an agent で未使用の名前を入力します。対話モードは Text のまま、Use the Microsoft Copilot harness を選んで Create します。
- Model でデプロイ済みのモデルを選び、Instructions に
学習用のアシスタントです。質問に日本語で簡潔に答えてください。と入力します。 - Tools → Harness tools で File system read・File system write・Shell・Web・Subagents をすべてオフにして Done を選びます。ほかのツールやスキルは追加しません。
- Save and start new chat を選び、設定した版が active になったら「どんな相談に対応できますか?」と送ります。テキスト応答が完了し、トレースにモデルの処理が記録されていることを確認します。[^harness-guide]
5.3 azd で作る
Azure Developer CLI(azd)を使うと、エージェントの定義をアプリのコードと一緒に管理できます。azd 1.37.0 以降と Foundry 拡張(azure.ai.agents は 1.0.0-beta.22 以降)を使います。未導入なら拡張をインストールし、既に導入済みでバージョンが足りなければ azd ext upgrade microsoft.foundry で更新します。[^harness-guide][^azd-extensions]
azd ext install microsoft.foundry
azd ai agent version
azd auth login
export AZD_ALPHA_ENABLE_AGENTS_MANAGED_HARNESS=true
次の 3 変数を、未使用のエージェント名、既存プロジェクトの ARM リソース ID、デプロイ済みモデルのデプロイ名に置き換えます。PROJECT_ID には SDK に渡す HTTPS エンドポイントではなく、Foundry プロジェクトの Properties にある Resource ID を指定します。[^research-quickstart]
AGENT_NAME="harness-demo-<unique-suffix>"
PROJECT_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
MODEL_DEPLOYMENT="<model-deployment-name>"
azd ai agent init "$AGENT_NAME" \
--no-prompt \
--kind prompt \
--agent-name "$AGENT_NAME" \
--project-id "$PROJECT_ID" \
--model-deployment "$MODEL_DEPLOYMENT" \
--instructions "学習用のアシスタントです。質問に日本語で簡潔に答えてください。"
cd "$AGENT_NAME"
このディレクトリの azure.yaml で、生成済みの host: azure.ai.agent のサービスに次の設定を反映します。<agent-service-name> は実際のサービスキーに読み替え、生成されたプロジェクト設定、モデル、名前、指示などは残します。この例では tools を以下の 1 項目だけにして、組み込みツールを既定で無効にします。[^harness-guide]
services:
<agent-service-name>:
host: azure.ai.agent
# 生成された既存フィールドは残す
harness:
type: microsoft_copilot_preview
tools:
- type: microsoft_copilot_toolset_preview
defaultConfig:
enabled: false
同じディレクトリでデプロイします。既存プロジェクトとモデルデプロイを再利用するため、この手順では新しい Foundry リソースやモデルデプロイを作りません。[^research-quickstart]
azd up --no-prompt
azd ai agent show --output json
show の出力で最新の版が active であることと、kind: prompt、harness.type: microsoft_copilot_preview、組み込みツールを無効にする設定を確認します。その後、新しい会話でテキスト応答を確かめます。[^harness-guide][^research-quickstart]
azd ai agent invoke --new-conversation --no-prompt "どんな相談に対応できますか?"
スキルと Web search を組み合わせる場合は、公式クイックスタートを使えます。SKILL.md のあるディレクトリを azure.ai.skill サービスで宣言し、エージェントの skills と uses から参照します。先に設定した microsoft_copilot_toolset_preview は残し、公開情報を検索する場合に限り、別の項目として type: web_search を追加します。組み込みの Web を有効にする必要はありません。[^research-quickstart][^harness-guide]
5.4 SDK で作る
Python の場合は azure-ai-projects 2.9.0 以降と azure-identity を使います。以下は Azure CLI のログインを DefaultAzureCredential から使う場合の準備例です。[^harness-guide][^function-calling]
python -m pip install "azure-ai-projects>=2.9.0" azure-identity
az login
endpoint には Foundry のプロジェクトエンドポイント、model にはデプロイ名を指定します。新規エージェントの定義で MicrosoftCopilotHarness() を指定し、MicrosoftCopilotToolsetPreview で組み込みツールを既定で無効にします。[^harness-guide]
呼び出しには、プロジェクト単位ではなくエージェント専用の Responses エンドポイントを使います。AIProjectClient の初期化には引き続きプロジェクトエンドポイントを指定し、get_openai_client の agent_name で呼び出し先を選びます。[^harness-guide]
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
MicrosoftCopilotHarness,
MicrosoftCopilotToolsetDefaultConfig,
MicrosoftCopilotToolsetPreview,
PromptAgentDefinition,
)
from azure.identity import DefaultAzureCredential
project = AIProjectClient(
endpoint="https://<account>.services.ai.azure.com/api/projects/<project>",
credential=DefaultAzureCredential(),
allow_preview=True,
)
agent = project.agents.create_version(
agent_name="harness-demo-<unique-suffix>",
definition=PromptAgentDefinition(
model="<model-deployment-name>",
instructions="学習用のアシスタントです。質問に日本語で簡潔に答えてください。",
harness=MicrosoftCopilotHarness(),
tools=[
MicrosoftCopilotToolsetPreview(
default_config=MicrosoftCopilotToolsetDefaultConfig(enabled=False),
)
],
),
)
print(f"作成したエージェント: {agent.name} (version {agent.version})")
openai = project.get_openai_client(agent_name=agent.name)
conversation = openai.conversations.create()
response = openai.responses.create(
conversation=conversation.id,
input="どんな相談に対応できますか?",
)
if response.status != "completed":
raise RuntimeError(f"応答が完了しませんでした: {response.status}")
print(response.output_text)
C#・TypeScript・Java の手順と SDK の対応バージョンも公式ガイドで確認できます。[^harness-guide]
6. 動作を確かめる
第 5 章の構成では、テキスト応答が完了し、トレースにモデルの処理が記録されていれば、基本の呼び出しを確認できています。ツールやスキルの動作は別のテストです。機能を追加したら、新しい会話で次を確認します。[^harness-guide][^research-quickstart]
- トレース: 追加した機能を必要とする質問を送り、期待したツールやスキルの呼び出しを調べます。たとえば Web search と調査スキルを追加したなら、公開情報について質問し、検索とスキルの両方の呼び出しを確認します。[^research-quickstart]
- 根拠の照合: 添付ファイルを使う場合、ファイル内の文書 ID や内容と回答を照合します。添付がワークスペースに配置されなかった場合も、テキストだけで処理が続くことがあります。[^harness-guide]
- 版の記録: エージェント名、版、参照スキルの版を記録し、同じ質問で比較します。エージェントの版は変更不能なスキルの版を参照するため、スキルを更新しただけでは既存のエージェントの版に反映されません。[^harness-guide]
7. 本番化の前に確認すること
確認基準日: 2026-11-20。下表は確認時点の公開情報です。導入判断の前には、最新の提供状態・料金・制約を公式資料で再確認してください。
表3 Copilot harness の導入判断で確認すること
| 項目 | 内容 |
|---|---|
| 提供状態 | Public preview。SLA はなく、Microsoft は本番利用を推奨していない[^harness-guide] |
| 課金 | 公式発表では、サンドボックスの vCPU・メモリの従量課金は 2026 年 12 月 1 日に開始予定。それ以前もモデル推論・有料ツール・接続先サービスには各料金が適用される[^harness-announcement] |
| 認可 | 利用者と会話の対応、文書の閲覧制御、外部操作の承認はアプリ側の責務 |
| ネットワーク | 閉域構成での対応範囲は Prompt エージェント全体より狭い場合がある。制限表で確認する[^harness-limits] |
| 変更不可 | 初期 public preview では harness は作成時のみ選択でき、後から切り替えられない[^harness-guide] |
8. まとめ
- Copilot harness は、Prompt エージェントの実行ループと環境を Foundry に任せる選択肢です。必要性は 3 択(harness なし / あり / Hosted)で判断します。
- ポータル・azd・SDK のいずれでも、組み込みツールを無効にしてテキスト応答を確かめるところから始めます。ツールやスキルを追加したら、トレースと回答の根拠を別に確認します。
- 実行を Foundry に任せても、利用者が業務データの閲覧や操作をしてよいかの判断はアプリ側に残ります。
- preview のため、本番化前に提供状態・課金・認可・ネットワーク対応を再確認してください。
9. 参考情報
- Quickstart: Create a web research agent — Web search とスキルを組み合わせた harness エージェントの一連の手順
- Hosted agents in Foundry Agent Service — 自前のフレームワークやループが必要な場合の選択肢
- Create a prompt agent with Microsoft Foundry Toolkit for Visual Studio Code — VS Code から Prompt エージェントを作る手順
- Microsoft Foundry の評価機能ガイド — 自動評価・人手評価・レッドチーミングの使い分け — エージェント作成後の品質評価の設計
[^harness-guide]: Use the Microsoft Copilot harness with prompt agents — Microsoft(確認日: 2026-11-20)
[^harness-announcement]: Introducing the Microsoft Copilot harness in Foundry Agent Service — Microsoft(確認日: 2026-11-20)
[^harness-limits]: Quotas and limits for Microsoft Foundry Agent Service — Microsoft(確認日: 2026-11-20)
[^skills-guide]: Use skills with Microsoft Foundry agents (preview) — Microsoft(確認日: 2026-11-20)
[^function-calling]: Use function calling with Microsoft Foundry agents — Microsoft(確認日: 2026-11-20)
[^azd-extensions]: Install the azd Foundry extensions — Microsoft(確認日: 2026-11-20)
[^research-quickstart]: Quickstart: Create a web research agent — Microsoft(確認日: 2026-11-20)






