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 つの設計判断

Microsoft Copilot harness の責任分界。Foundry はモデルとツールの呼び出しを調整し、業務アプリは利用者の認可と独自関数の実行を担う

図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 ポータルで作る

公式のポータル手順に沿って、最初の質問を送る前にツール設定を保存します。

  1. Microsoft Foundry で New Foundry を有効にし、対応リージョンのプロジェクトを選びます。
  2. Build an agent → Create an agent で未使用の名前を入力します。対話モードは Text のまま、Use the Microsoft Copilot harness を選んで Create します。
  3. Model でデプロイ済みのモデルを選び、Instructions に 学習用のアシスタントです。質問に日本語で簡潔に答えてください。 と入力します。
  4. Tools → Harness tools で File system read・File system write・Shell・Web・Subagents をすべてオフにして Done を選びます。ほかのツールやスキルは追加しません。
  5. 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]

bash
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]

bash
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]

yaml
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]

bash
azd up --no-prompt
azd ai agent show --output json

show の出力で最新の版が active であることと、kind: prompt、harness.type: microsoft_copilot_preview、組み込みツールを無効にする設定を確認します。その後、新しい会話でテキスト応答を確かめます。[^harness-guide][^research-quickstart]

bash
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]

bash
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]

python
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. 参考情報

[^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)