🧾 エージェントの出力・ツール呼び出し・監査文脈を束ねる評価契約 - ECP

Evaluation Context Protocol（ECP）は、AI エージェントの評価を「フレームワークに依存しない JSON-RPC の契約」として定義する提案です。2026-08-18 に arXiv へ公開された論文 The Evaluation Context Protocol (ECP): A Portable Contract for AI Agent Evaluation と、Apache-2.0 の参照実装 evaluation-context-protocol/ecp がセットになっています。

この記事では、ECP の契約面・内部構造・データモデルを整理し、実際に ecp CLI を CI へ組み込むところまでを扱います。あわせて、論文が主張する範囲と参照実装が実際にできることの差分、および現時点で期待してはいけない機能も明示します。

記述はすべて 2026-08-22 時点の参照実装（パッケージ線 0.9.0）を基準にしています。

ECP とは何か

ECP は、エージェントが返す 3 つの情報を、フレームワーク横断で同じ形に揃えて検査するための契約層です。

• public_output — ユーザーに見える最終出力
• tool_calls — エージェントが宣言したツール呼び出し列
• evaluation_context — 評価者向けの監査文脈

論文の出発点は、静的ベンチマークと最終出力だけの採点では、不正な経路・ショートカット・実行ごとの一貫性不足を見逃すという問題意識です。ツール実行面は MCP が共通言語になりつつある一方、評価面には同等の契約が無い。ECP はその欠落を、小さな JSON-RPC インタフェースと宣言的な manifest で埋めようとします。

現行の契約面

MCP との関係

ECP と MCP は競合せず、直交する面を担当します。

ECP は観測バックエンド・ベンチマークコーパス・本番オーケストレータを置き換えるものではありません。

論文の主張と参照実装の現状

採用判断で最も重要なのは、論文が語る設計と、いま動く実装の差です。

先行研究との位置関係

特徴と類似技術との比較

ECP の性質を、実装できることベースで並べます。

• ベンダー中立の評価契約として、エージェント結果を JSON-RPC 2.0 で露出する。
• 最終出力・ツール呼び出し列・監査文脈を独立に採点できる。
• 必須ツールの呼び出し漏れや引数の不一致があれば、最終出力が正しくてもシナリオを失敗にできる。ただし tool_usage は肯定チェックのみで、禁止ツールを呼んだことを理由に落とす grader はありません。
• 監査文脈は evaluator-safe な正当化でよく、生の推論トレース開示は必須ではない。
• plain Python と主要フレームワークを同一契約へ寄せられる。
• manifest YAML でシナリオと grader を宣言できる。
• ローカル実行と CI 実行を同じ契約で扱える。
• HTML / JSON レポートと構造化 audit を出せる。
• conformance harness で独立実装の適合を確認できる。
• pytest fixture で既存の Python テストへ段階導入できる。
• CSV / JSONL データセットからシナリオを展開できる。
• RPC 単位と wall-clock の実行上限を持てる。
• 障害時は失敗として記録しつつ後続シナリオへ進み、レポートを残す。
• 保存済みレポート列から pass-rate の回帰シグナルを取れる。

類似ツールとの比較

ユースケース別の選び方

構造

ECP の層構成は、論文 Fig. 2 の Agent → SDK → Protocol → Runtime → Consumer と、リポジトリの sdk/ / runtime/ / schema/ / spec/ / client/ / server/ が対応します。以下では C4 の 3 段階で整理します。

システムコンテキスト

開発者・CI runner・評価者と、ECP 契約層、および外部のエージェント実行基盤・基盤モデル・観測バックエンド・CI 基盤との関係です。

grader engine はこの粒度では ECP 契約層（runtime）の責務に含まれます。次のコンテナ図で独立コンテナとして現れます。

コンテナ

各層は直下の契約だけに依存します。SDK と runtime は参照実装であり、契約そのものは JSON-RPC なので、適合する任意言語の実装が参加できます。

コンポーネント

CLI コマンド・runtime 内部モジュール・schema ファイル・adapter・transport の依存関係です。

CLI コマンドの責務です。init と doctor は runner も manifest ローダも使わないため、図では省いています。

runtime 内部モジュールと schema の対応です。

adapter は各フレームワークの実行結果を Result へ写します。

adapter が薄い翻訳であることが移植性の根拠です。一方で、各フレームワークの中間推論の露出度が異なるため、evaluation_context は構造化された証跡ではなく、捕捉テキストの連結になり得ます。構造化スキーマ化は未完了の課題です。

TypeScript SDK は sdk/typescript/package.json があるだけで、ツリー上にソースはありません（package 版 0.1.0）。論文の記述より実体は薄い状態です。

JSON-RPC メソッド

契約面のメソッドは 3 つだけです。

データモデル

属性は schema/*.schema.json と SDK の Result dataclass を正とします。論文の散文との差分は後段で明示します。

概念モデル

入れ子は所有、矢印は利用を表します。

情報モデル

所有は *--、利用は --> です。

Manifest と Scenario と Step

Grader

AgentResult と ToolCall と Usage

論文の散文が採点対象として挙げるのは public_output / tool_calls / evaluation_context と任意の logs です。機械可読契約である agent-result.schema.json は、これに加えて status と usage を定義します。しかも唯一の必須フィールドは status です。論文だけを読んで実装すると、この差分を取りこぼします。

ToolCall は name（必須）と arguments（任意の map）で、additionalProperties は true です。Usage は input_tokens / output_tokens / total_tokens の非負整数で、未観測ならフィールドごと省略します。

Report と AuditRecord

Report で注意すべき点は集計単位です。runner の集計処理により、passed と total は シナリオ数ではなく check 件数 を数えます。シナリオ 1 件に grader を 5 個書けば、total は 5 増えます。

論文と実装の差分

導入手順

前提

• Python は >=3.9。
• CLI エントリポイントは ecp。
• サブコマンドは run / validate / doctor / init / conformance / trend のみ。
• llm_judge を使う場合は OPENAI_API_KEY が必要。

インストール

現行線は 0.9.0 です。公式ドキュメントの quickstart には 0.7.0 の pin が残っていますが、PyPI の現行版が正です。

pip install "ecp-runtime==0.9.0" "ecp-sdk==0.9.0"

フレームワーク別の extras です。

pip install "ecp-sdk[langchain]==0.9.0"
pip install "ecp-sdk[crewai]==0.9.0"
pip install "ecp-sdk[llamaindex]==0.9.0"
pip install "ecp-sdk[pydanticai]==0.9.0"

ecp-sdk 本体はゼロ依存です。extras は crewai / langchain / llama-index / pydantic-ai を引き込みます。ecp-runtime は typer / pyyaml / pydantic / rich / litellm / Jinja2 に依存します。

バージョン確認

python -c "import importlib.metadata as m; print(m.version('ecp-runtime'), m.version('ecp-sdk'))"
ecp doctor

ecp doctor は Python 版・実行ファイル・作業ディレクトリ・OPENAI_API_KEY の有無・git の有無を表示するだけです。エージェントには接続しません。

初期プロジェクト作成

ecp init
ecp validate ecp_eval/manifest.yaml
ecp run --manifest ecp_eval/manifest.yaml

既存ファイルがある場合、ecp init は上書きせず終了します。上書きするには --force を付けます。

init が書き出すスターターは、@agent / @on_step / @on_reset / Result / serve の最小構成です。

from ecp import Result, agent, on_reset, on_step, serve


@agent(name="StarterAgent")
class StarterAgent:
    def __init__(self):
        self.seen = []

    @on_step
    def step(self, user_input: str):
        self.seen.append(user_input)
        return Result(
            public_output=f"Echo: {user_input}",
            evaluation_context="The starter agent echoed the user input.",
            tool_calls=[{"name": "echo", "arguments": {"text": user_input}}],
        )

    @on_reset
    def reset(self):
        self.seen.clear()


if __name__ == "__main__":
    serve(StarterAgent())

利用方法

必須パラメータと既定値

Manifest の検証と実行

公開契約は schema/manifest.schema.json で、必須項目は manifest_version（const v1）/ name / target / scenarios です。ただし ecp validate は schema ファイルを直接読むのではなく、それと整合する pydantic モデルで検証します。

ecp validate examples/customer_support_demo/manifest.yaml
ecp run --manifest examples/customer_support_demo/manifest.yaml --json
ecp run --manifest examples/customer_support_demo/manifest.yaml --report report.html
ecp run --manifest examples/customer_support_demo/manifest.yaml --json-out report.json
ecp run --manifest examples/customer_support_demo/manifest.yaml --audit-out ecp_audit.json

target は stdio 用のコマンド、または Streamable HTTP のエンドポイントです。

target: "http://127.0.0.1:8765/ecp"

grader を書く

参照実装のデモ manifest がそのまま実例になります。

manifest_version: "v1"
name: "Customer Support Refund Policy"
target: "python examples/customer_support_demo/agent.py"

scenarios:
  - name: "Eligible refund uses order lookup and policy check"
    steps:
      - input: "I want a refund for order A100."
        graders:
          - type: text_match
            field: public_output
            condition: contains
            value: "eligible for a refund"
          - type: text_match
            field: evaluation_context
            condition: contains
            value: "refund_eligible=True"
          - type: llm_judge
            field: public_output
            prompt: "Does the output clearly state if the order is eligible for a refund? Must confirm eligibility."
          - type: tool_usage
            tool_name: "lookup_order"
            arguments:
              order_id: "A100"
          - type: tool_usage
            tool_name: "check_refund_policy"
            arguments:
              order_id: "A100"

grader の挙動です。

• text_match は指定フィールドへの文字列一致・不一致・正規表現。
• llm_judge は LiteLLM 経由で判定し、応答内の RESULT: PASS / RESULT: FAIL を読み取る。
• tool_usage は tool_name の完全一致と arguments の部分集合一致。照合時のツール名キーは name / tool / id、引数キーは arguments / args を順に試す。

この manifest 1 件で check は 5 件になります。前述のとおり Report の total はシナリオ数ではなく、この 5 を数えます。

SDK でエージェントを実装する

from ecp import Result, agent, on_step, serve


@agent(name="SupportAgent")
class SupportAgent:
    @on_step
    def step(self, user_input: str):
        return Result(
            public_output="Order A100 is eligible for a refund.",
            evaluation_context="Checked order A100 and confirmed it is inside the 30-day refund window.",
            tool_calls=[
                {"name": "lookup_order", "arguments": {"order_id": "A100"}},
                {"name": "check_refund_policy", "arguments": {"order_id": "A100"}},
            ],
        )


if __name__ == "__main__":
    serve(SupportAgent())

Streamable HTTP で待ち受ける場合は serve_http を使います。

from ecp import serve_http

if __name__ == "__main__":
    serve_http(SupportAgent(), host="127.0.0.1", port=8765, path="/ecp")

pytest から使う

ecp-runtime は pytest プラグインを登録するため、既存のテストへ段階的に混ぜられます。

def test_customer_support(ecp_agent):
    result = ecp_agent.step("I need a refund")
    assert "refund" in result.get("public_output", "").lower()

pytest test_agent.py --ecp-target="python agent.py"

conformance と trend

ecp conformance --target "python examples/customer_support_demo/agent.py"
ecp trend "results/run-*.json" --window 20 --exit-on-regression

CI への組み込み

流れは、プルリクエスト → manifest 検証 → ecp run → grader 判定 → 非ゼロ終了でビルドを落とす、です。

参照実装リポジトリの .github/workflows/ci.yml は参照実装自身の unittest / ruff / mkdocs / package build であって、利用者向けのテンプレートではありません。利用者向けの YAML 例は公式の docs/ci.md にあります。

name: ECP evals

on:
  pull_request:
  push:
    branches: [main]

jobs:
  evals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install "ecp-runtime==0.9.0" "ecp-sdk==0.9.0"
      - run: ecp validate examples/customer_support_demo/manifest.yaml
      - run: |
          ecp run --manifest examples/customer_support_demo/manifest.yaml \
            --timeout 60 --max-duration 900 \
            --json-out ecp-report.json --audit-out ecp-audit.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: ecp-report
          path: |
            ecp-report.json
            ecp-audit.json

運用

起動と実行順序

評価の起動単位は manifest です。runtime は target を spawn し、agent/initialize → 各 agent/step → シナリオ間の agent/reset を駆動します。

• 起動前に ecp validate を通す。
• 契約適合だけを見たいときは ecp conformance を使う。
• 既定では grader 失敗が 1 件以上あれば ecp run は exit 2。

ecp validate examples/customer_support_demo/manifest.yaml
ecp run --manifest examples/customer_support_demo/manifest.yaml \
  --timeout 60 --max-duration 900 \
  --json-out ecp-report.json --audit-out ecp-audit.json \
  --report report.html

実行境界と degrade

限界超過・クラッシュ・プロトコル違反が起きても、ラン全体を abort せず degrade します。

1. 当該 step を failed として記録する。結果が返らなくても execution 系の failed check を最低 1 件付与する。
2. 同一シナリオの残り step を skipped にする。
3. 次のシナリオは新しいエージェントプロセスで継続する。
4. JSON / HTML / audit はラン末尾まで残す。

これは破壊的変更を伴う改善で、以前はハングがラン全体を殺し、レポート自体が欠落し得ました。現行はレポートに failed check が残ります。

状態確認

step 級の exit_reason です。

ラン級の exit_reason には skipped がありません。ok / timeout / transport_error / protocol_error / agent_error / max_duration_exceeded / error の 7 値です。ok 以外なら degrade 済みと読みます。

読み違えを避ける要点は 1 つです。steps_planned と steps_executed の差は、その pass rate が意図より少ないステップ上で測られたことを意味します。合格率だけを見るとハングが成功に見えます。

ログと版の追従

CLI は標準の logging を使い、既定 INFO、--verbose で DEBUG です。エージェント側の評価者向け実行ログは任意の logs、トークン会計は任意の usage で、観測できない場合は 0 ではなく省略します。

回帰ゲート

ecp trend "results/run-*.json" --window 20 --exit-on-regression

これは pass^k の推定ではなく、集約 pass-rate に対する粗い第一歩と位置づけられています。

ベストプラクティス

CI での組み立て順

1. ecp validate で manifest 検証を先に通す。
2. ecp conformance で契約適合を分離して確認する。
3. ecp run に --timeout と --max-duration を必ず付ける。
4. if: always() で report / audit を artifact 化する。
5. 蓄積した JSON に ecp trend ... --exit-on-regression を掛ける。
6. llm_judge を使うときだけ secrets 経由で API キーを渡す。

決定的な grader（text_match / tool_usage）を先に通し、llm_judge は主観の残差に限定する tiered 構成が現実的です。ただし、安価な grader で高価な judge をゲートするネイティブな tiered 実行は roadmap であり、1 つの manifest に grader を並べても judge 呼び出しは省略されません。コストを実際に削るなら、決定的チェック用と llm_judge 用で manifest と CI ジョブを分け、前者が成功したときだけ後者を起動します。評価コストの目安として、LLM judge の費用を本番 LLM 費用の 10〜15% 以下に抑えるガードレールが提唱されています。これは評価スイート全体の実測値ではなく運用上の目安で、25% に近づいたらサンプリング削減か judge モデルの格下げを検討します。

held-out を分離する

誤解: 評価セットの失敗信号でプロンプトを直接直せば、スコア上昇は汎化の改善を意味する。

反証: holdout 不足とショートカットにより、見かけの成功は脆いことが繰り返し示されています。開発中のセットに合わせ込むと、そのセット上でしか通らないエージェントができます。

推奨: 開発用セットと held-out ゲートを分ける。封印された held-out manifest は roadmap にあるものの現行未実装なので、当面はディレクトリ分離とレビュー規約で境界を運用します。

LLM judge を校正する

論文が紹介する推奨は、golden label 最低 100 件、Cohen's κ ≥ 0.6、典型 30 日での再校正、binary の pass/fail です。これらは ECP の JSON-RPC や manifest が定める規範要件ではありません。現行の llm_judge は判定文字列のパースだけを行い、κ・golden・再校正日を機械的に検査する仕組みは持ちません。

推奨: 決定可能な期待は text_match / tool_usage に寄せる。judge 領域だけ人間ラベルで校正し、κ と再校正日はチーム側の台帳で管理する。温度は 0 固定、モデルは環境変数で明示する。

evaluation_context を生の CoT にしない

ECP は raw chain-of-thought の開示を必須にしません。evaluation_context は evaluator-safe な正当化を書く場所です。

• 新規エージェントは evaluation_context を使う。private_thought は互換 alias。
• redaction hook は roadmap で現行未実装なので、発行前にアプリ側でマスキングする。

現時点で期待してはいけないこと

• experimental / early-stage であり、完成した標準ではない。
• 評価面・メソッド集合・grader 家族は暫定で、変更予定である。
• 実証（fault injection / 独立実装の相互運用 / オーバーヘッド）は未実施である。
• adapter 由来の evaluation_context は構造化証跡ではなく、捕捉テキストの連結になり得る。
• delegation のネイティブ表現が無い。マルチエージェントの handoff は通常の tool_calls へ写像される。
• 公式ドキュメントの quickstart は 0.7.0、パッケージ線は 0.9.0 とずれている。
• policy_check / authority limits は roadmap で、現行 grader には無い。
• --export の実装対象は langsmith のみである。
• capabilities は informational である。
• paused の human-in-the-loop 意味論は仕様上まだ薄い。
• Streamable HTTP は評価面の契約であり、認証・認可は別責務である。

マルチエージェントの扱い

論文の two-agent 例では、planner と writer の handoff を通常の tool call として記録します。採点はできますが、ECP に delegation のネイティブ表現はありません。拡張候補として agent/handoff 通知と subagent 識別子が挙がっている段階です。現行契約の語彙は「単一エージェントが他エージェントをツールとして呼ぶ」に留まります。

adapter に構造化を期待しすぎない

誤解: adapter 経由にした瞬間、構造化された evidence が揃う。

反証: 出力の構造度は、下位フレームワークが露出する情報の上限に束縛されます。マルチエージェント系は時間変動が大きく、アーキテクチャの差がモデル差より支配的になり得ることも報告されています。

推奨: 重要な契約は tool_usage と public_output の決定的 grader で固定する。adapter 由来の evaluation_context には緩い contains に留めるか、実装側で明示的な構造化要約を返すようにする。

pass@k と pass^k を混同しない

各試行が独立で成功確率が一定と仮定したとき、1 試行の成功率が 70% なら pass@3 は約 97.3%、pass^3 は約 34.3% です。同じエージェントでも、どちらを見るかで印象が正反対になります。実際のランはタスク難度・共有障害・キャッシュ・同一プロンプトによって試行間が相関するため、この算術例をそのまま当てはめず、反復実行から直接推定します。現行の ecp trend は単発実行の pass-rate 回帰であり、k 回実行のネイティブ対応は roadmap です。

成熟度を運用へ翻訳する

なお GitHub リポジトリの説明文には “enforcing authority limits” が含まれますが、現行の grader 家族は 3 種のみです。説明文どおりの権限強制を期待すると過大評価になります。

トラブルシューティング

実行境界と終了コード

• ハングを pass と読まないために、exit_reason と steps_planned / steps_executed を必ず照合する。
• CI では --timeout と --max-duration を併用する。

版・依存・エクスポート

• インストール pin は公式サイトの記載ではなく PyPI の 0.9.0 を正とする。
• llm_judge は litellm と OPENAI_API_KEY に依存する。
• --export の実装対象は langsmith のみ。

契約フィールドと権限の読み違い

• 新規エージェントは evaluation_context を使う。private_thought は互換 alias。
• capabilities は informational で、機能ゲートには使えない。
• リポジトリ説明文の authority limits と、policy_check 未実装という現実を切り分ける。

症状別の対処

まとめ

ECP は、エージェント評価を「ホスト型プラットフォームの内側」から「移植可能な JSON-RPC 契約」へ引き出す提案です。

• 契約面は小さい。メソッド 3 種、採点フィールド 3 種、grader 3 種。
• 出力だけでなくツール呼び出しと監査文脈を独立に採点できるため、最終出力が正しくても必須ツールを踏んでいなければ落とせる。禁止経路の拒否はアプリ側の責務。
• CI からは validate → conformance → run → trend を起動でき、終了コードをゲートに使える。本番ゲートとして信頼するかは、自組織での検証後に判断する。
• 一方で experimental であり、policy_check・sealed held-out・k 回実行・OTel 写像・redaction hook はいずれも roadmap。
• 読み違えやすい落とし穴は 3 つ。Report の total は check 件数であること、capabilities は informational であること、リポジトリ説明文の authority limits は未実装であること。

いま採用するなら、決定的 grader を CI のゲートに置き、llm_judge は主観の残差に限定し、held-out はディレクトリ分離で自前運用する構成が現実的です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

論文

• The Evaluation Context Protocol (ECP): A Portable Contract for AI Agent Evaluation（arXiv abs）
• HTML 全文
• PDF

公式仕様・実装

• Specification
• Quickstart
• GitHub evaluation-context-protocol/ecp
• README
• CHANGELOG
• spec/protocol.md
• runtime cli.py
• runtime graders.py
• sdk decorators.py
• manifest.schema.json
• agent-result.schema.json
• audit.schema.json
• report.schema.json
• tool-call.schema.json
• customer_support_demo/manifest.yaml
• docs/ci.md
• PyPI ecp-runtime
• PyPI ecp-sdk

関連する研究・記事

• Kapoor et al., AI Agents That Matter
• MAESTRO（arXiv:2601.00481）
• Towards a Science of AI Agent Reliability（arXiv:2602.16666）
• Digital Applied, Building an AI Agent Evaluation Pipeline: 2026 Methodology

関連ツール

• Model Context Protocol
• Eval Protocol
• OpenTelemetry GenAI semantic conventions
• LangSmith docs
• Langfuse docs
• Arize Phoenix