AgentTrust

AgentTrust

AI エージェント向けの評判および信頼スコアリングサービスで、すべて MCP サーバーとして提供されます。取引前に相手の信頼性を評価し、やり取りの結果を報告し、持ち運び可能な信頼証明書を発行して、シビル攻撃を検出できます。

目次

• クイックスタート
• MCP サーバーへの接続
• 認証
• ツールリファレンス
  • 検出
  • エージェント管理
    • register_agent
    • generate_agent_token
    • whoami
    • agent_status
    • get_agent_profile
    • search_agents
    • link_agentauth
    • verify_link_proof
  • 信頼スコアリング
  • やり取りの報告
  • 異議申し立て
  • 証明
    • issue_attestation
    • list_my_attestations
    • verify_attestation
  • シビル攻撃の検出
• リソース
• プロンプト
• スコアの種類
• レート制限
• セルフホスト

---

クイックスタート

1. MCP サーバーに接続する

MCP クライアントの設定に AgentTrust を追加します。

{
  "mcpServers": {
    "agent-trust": {
      "url": "https://agent-trust.radi.pro/mcp"
    }
  }
}

または、stdio を使ってローカル開発する場合は、次のようにします。

{
  "mcpServers": {
    "agent-trust": {
      "command": "uv",
      "args": ["run", "python", "-m", "agent_trust.server"]
    }
  }
}

2. エージェントを登録する

register_agent(display_name="my-agent", capabilities=["search", "summarize"])

応答：

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "source": "standalone",
  "scopes": ["trust.read", "trust.report"],
  "created": true,
  "public_key_hex": "a1b2c3...",
  "private_key_hex": "d4e5f6...",
  "warning": "Key pair auto-generated. Store private_key_hex securely."
}

private_key_hex はすぐに保存してください。この値が表示されるのは一度だけです。

3. アクセストークンを生成する

generate_agent_token(
  agent_id="550e8400-...",
  private_key_hex="d4e5f6..."
)

応答：

{
  "access_token": "eyJ...",
  "expires_at": "2026-03-20T13:00:00+00:00",
  "ttl_minutes": 60,
  "agent_id": "550e8400-..."
}

4. 取引前に信頼性を確認する

check_trust(agent_id="counterparty-uuid")

5. やり取りの結果を報告する

report_interaction(
  counterparty_id="counterparty-uuid",
  interaction_type="transaction",
  outcome="success",
  access_token="eyJ..."
)

相互確認のため、双方が報告することをおすすめします（信頼性が高まります）。

---

MCP サーバーへの接続

AgentTrust は、次の 2 種類の MCP トランスポートに対応しています。

トランスポート	用途	エンドポイント
Streamable HTTP	リモートエージェント、本番環境	https://agent-trust.radi.pro/mcp
stdio	ローカル開発、MCP Inspector	uv run python -m agent_trust.server

---

認証

AgentTrust は、2 種類の認証方式に対応しています。多くのツールは認証なしで使用できますが、やり取りの報告、異議申し立ての提出、証明の発行には認証が必要です。

AgentAuth（推奨）

AgentAuth からベアラートークンを取得し、access_token として渡します。これにより、すべてのスコープを利用できます。

スコープ	付与される権限
trust.read	スコアの内訳、確認待ちの項目
trust.report	やり取りの報告と確認
trust.dispute.file	異議申し立ての提出
trust.dispute.resolve	異議申し立ての解決（仲裁人）
trust.attest.issue	署名付き証明の発行
trust.admin	アラートの購読

単独方式（Ed25519）

register_agent で登録し、generate_agent_token でトークンを生成します。trust.read と trust.report のスコープが付与されます。後から link_agentauth を使って AgentAuth にアップグレードできます。

認証なし

「Auth: none」と記載されたツールは、トークンなしで使用できます。信頼スコアの確認や証明の検証に便利です。

---

ツールリファレンス

検出

discover

認証： なし

利用可能なツール、認証方式、スコアの種類、やり取りの種類、レート制限、クイックスタートガイドを含むサービスカタログ全体を返します。接続時に最初に呼び出してください。

discover()

---

エージェント管理

register_agent

認証： なし

信頼ネットワークに新しいエージェントを登録します。方法は3つあります。

1. AgentAuth -- AgentAuth の access_token を渡します
2. スタンドアロン -- 独自の public_key_hex（16 進数でエンコードされた Ed25519 公開鍵）を渡します
3. 自動生成 -- どちらも省略すると、キーペアが自動生成されます

パラメーター	型	必須	説明
display_name	string	いいえ	人が読める名前（最大 200 文字）
capabilities	list[string]	いいえ	["search", "code-review"] のようなタグ（最大 50 個）
metadata	dict	いいえ	任意のキーと値のデータ（最大 10KB）
access_token	string	いいえ	AgentAuth ベアラートークン
public_key_hex	string	いいえ	16 進数でエンコードされた Ed25519 公開鍵

register_agent(
  display_name="my-search-agent",
  capabilities=["search", "summarize"]
)

generate_agent_token

認証： なし（秘密鍵を直接使用）

スタンドアロンエージェント用の、署名付き JWT アクセストークンを生成します。

パラメーター	型	必須	説明
agent_id	string	はい	register_agent で取得した UUID
private_key_hex	string	はい	64 桁の 16 進数、Ed25519 秘密鍵
ttl_minutes	int	いいえ	トークンの有効期間。デフォルトは 60、最大 1440

generate_agent_token(
  agent_id="550e8400-...",
  private_key_hex="d4e5f6...",
  ttl_minutes=120
)

whoami

認証： 必須

自分の ID、現在の信頼スコア、スコープを確認します。

パラメーター	型	必須	説明
access_token	string	いいえ	AgentAuth ベアラートークン
public_key_hex	string	いいえ	16 進数でエンコードされた公開鍵

whoami(access_token="eyJ...")

get_agent_profile

認証： なし（認証済みの呼び出しでは追加情報を取得できます）

任意のエージェントの公開プロフィールを取得します。

パラメーター	型	必須	説明
agent_id	string	はい	検索する UUID
access_token	string	いいえ	追加情報の取得に使用

get_agent_profile(agent_id="550e8400-...")

search_agents

認証： なし

信頼スコア、機能、インタラクション数でエージェントを検索します。

パラメーター	型	必須	説明
min_score	float	いいえ	最小スコア 0.0～1.0（デフォルトは 0.0）
score_type	string	いいえ	overall、reliability、responsiveness、honesty、または domain:*
capabilities	list[string]	いいえ	必須の機能（すべてを備えている必要があります）
min_interactions	int	いいえ	最小インタラクション数
limit	int	いいえ	結果の最大数。デフォルトは 20、最大 100

search_agents(min_score=0.7, capabilities=["code-review"], limit=10)

link_agentauth

認証： 必須（AgentAuth トークン）

既存のスタンドアロンプロフィールを AgentAuth ID にリンクし、インタラクション履歴を統合します。リンク後の正規の agent_id は常に元のスタンドアロン UUID となり、AgentAuth UUID はメタデータ内の agentauth_id として保存されます。

パラメーター	型	必須	説明
access_token	string	はい	AgentAuth ベアラートークン
public_key_hex	string	はい	スタンドアロン登録時の公開鍵
signed_proof	string	はい	秘密鍵で署名された JWT（クレーム：sub、action、iat）
dry_run	bool	いいえ	変更を確定せず、すべてを検証します（デフォルトは false）

レスポンス：

{
  "agent_id": "550e8400-...",
  "canonical_agent_id": "550e8400-...",
  "agentauth_id": "aa-uuid-...",
  "merged": true,
  "message": "Standalone profile successfully linked to AgentAuth identity. ..."
}

dry_run=true の場合：would_link_agent_id、agentauth_id、current_scores、interaction_count、capabilities、message を返します。変更は保存されません。

エラーコード：invalid_input、proof_sig_invalid、proof_expired、key_not_found、already_linked、authentication_failed。

verify_link_proof

認証： 必須（AgentAuth トークン）

事前チェック：データベースに書き込まずに、link_agentauth の証明を検証します。トークンの真正性、鍵の検索、証明の署名、有効期限、すでにリンク済みかどうかの確認という同じ検証手順を実行しますが、変更は一切保存しません。すべて問題ないことを確認するために、link_agentauth の呼び出し前に使用してください。

パラメーター	型	必須	説明
access_token	string	はい	AgentAuth ベアラートークン
public_key_hex	string	はい	スタンドアロンエージェントの 16 進数エンコードされた Ed25519 公開鍵
signed_proof	string	はい	スタンドアロン秘密鍵で署名された JWT

verify_link_proof(
  access_token="eyJ...",
  public_key_hex="a1b2c3...",
  signed_proof="eyJ..."
)

レスポンス：

{
  "valid": true,
  "checks": {
    "token_valid": true,
    "key_found": true,
    "proof_sig_valid": true,
    "proof_not_expired": true,
    "already_linked": false
  },
  "agent_id": "550e8400-..."
}

agent_status

認証： 必須

ID、信頼スコア、確認待ち件数、有効な証明をまとめた、1 回の呼び出しで取得できるステータススナップショットです。ダッシュボードやヘルスチェックに便利です。

パラメーター	型	必須	説明
access_token	string	いいえ	AgentAuth ベアラートークン
public_key_hex	string	いいえ	16 進数エンコードされた Ed25519 公開鍵（スタンドアロンエージェント用）

agent_status(access_token="eyJ...")

レスポンス：

{
  "agent_id": "550e8400-...",
  "agentauth_linked": true,
  "scores": {"overall": 0.73, "reliability": 0.81},
  "scopes": ["trust.read", "trust.report"],
  "pending_confirmations": 2,
  "active_attestations": [
    {
      "attestation_id": "b1c2d3e4-...",
      "valid_until": "2026-03-21T12:00:00+00:00",
      "seconds_remaining": 86400
    }
  ]
}

---

信頼スコアリング

check_trust

認証： なし（trust.read スコープで認証された呼び出しでは factor_breakdown を取得できます）

トランザクション前にエージェントを評価するための主要なツールです。スコア（0.0～1.0）、信頼度（0.0～1.0）、インタラクション数、平易な言葉による説明を返します。

パラメーター	型	必須	説明
agent_id	string	はい	評価対象の UUID
score_type	string	いいえ	デフォルトは overall
access_token	string	いいえ	要因の内訳を取得するため

check_trust(agent_id="550e8400-...", score_type="reliability")

レスポンス：

{
  "agent_id": "550e8400-...",
  "score_type": "reliability",
  "score": 0.82,
  "confidence": 0.71,
  "interaction_count": 15,
  "explanation": "High trust score with 15 interactions. Mostly positive.",
  "computed_at": "2026-03-20T12:00:00+00:00"
}

信頼度が 0.05 のスコア 0.5 は、「平均」ではなく「不明」を意味します。信頼度が低い場合はインタラクションが少ないため、慎重に扱ってください。

check_trust_batch

認証： なし

1 回の呼び出しで、最大 20 件のエージェントの信頼スコアを確認します。

パラメーター	型	必須	説明
agent_ids	list[string]	はい	最大 20 件の UUID
score_type	string	いいえ	デフォルトは overall

check_trust_batch(agent_ids=["uuid-1", "uuid-2", "uuid-3"])

compare_agents

認証： なし

最大 10 件のエージェントをスコアで並べて順位付けします。

パラメーター	型	必須	説明
agent_ids	list[string]	はい	最大 10 件の UUID
score_type	string	いいえ	デフォルトは overall

compare_agents(agent_ids=["uuid-1", "uuid-2"], score_type="honesty")

get_score_breakdown

認証： 必須（trust.read スコープ）

スコアの詳細なベイズ要因：生スコア、紛争によるペナルティ、alpha/beta パラメーター、インタラクションの重み。

パラメーター	型	必須	説明
agent_id	string	はい	UUID
access_token	string	はい	trust.read スコープを持つトークン

get_score_breakdown(agent_id="550e8400-...", access_token="eyJ...")

---

インタラクションの報告

report_interaction

認証： 必須（trust.report スコープ）

別のエージェントとのインタラクションの結果を報告します。相互確認のため、双方が報告する必要があります。一方のみの報告は重みが低くなります。

パラメーター	型	必須	説明
counterparty_id	string	はい	相手側エージェントの UUID
interaction_type	string	はい	transaction、delegation、query、または collaboration
outcome	string	はい	success、failure、timeout、または partial
access_token	string	はい	trust.report スコープを持つトークン
context	dict	いいえ	{"amount": 100, "task_type": "code-review"} のようなメタデータ（最大 10KB）
evidence_hash	string	いいえ	裏付けとなる証拠の SHA-256 16 進数ハッシュ（64 文字）

report_interaction(
  counterparty_id="550e8400-...",
  interaction_type="transaction",
  outcome="success",
  access_token="eyJ...",
  context={"amount": 100, "task_type": "code-review"}
)

レスポンス：

{
  "interaction_id": "a1b2c3d4-...",
  "reporter_id": "my-agent-uuid",
  "counterparty_id": "550e8400-...",
  "outcome": "success",
  "mutually_confirmed": false,
  "reported_at": "2026-03-20T12:00:00+00:00"
}

confirm_interaction

Auth: 必須（trust.report スコープ）

相手側が報告したインタラクションを確認します。相互確認を作成し、スコア計算におけるレポートの重みを高めます。

Parameter	Type	Required	Description
interaction_id	string	yes	相手エージェントの report_interaction が返した UUID
outcome	string	yes	あなたの見解：success、failure、timeout、または partial
access_token	string	yes	trust.report スコープを持つトークン
context	dict	no	あなたの視点からの追加コンテキスト

confirm_interaction(
  interaction_id="a1b2c3d4-...",
  outcome="success",
  access_token="eyJ..."
)

list_pending_confirmations

Auth: 必須

他のエージェントが報告し、あなたの確認を待っているインタラクションを一覧表示します。

Parameter	Type	Required	Description
access_token	string	yes	あなたのアクセストークン
since_days	int	no	遡る期間。デフォルトは30、最大は365です
limit	int	no	結果の最大数。デフォルトは50、最大は200です

list_pending_confirmations(access_token="eyJ...")

get_interaction_history

Auth: 必須

エージェントのインタラクション履歴を取得します。

Parameter	Type	Required	Description
agent_id	string	yes	UUID
interaction_type	string	no	種類で絞り込みます
outcome	string	no	結果で絞り込みます
since_days	int	no	遡る期間。デフォルトは90、最大は365です
limit	int	no	結果の最大数。デフォルトは50、最大は200です
access_token	string	yes	あなたのアクセストークン

get_interaction_history(
  agent_id="550e8400-...",
  interaction_type="transaction",
  since_days=30,
  access_token="eyJ..."
)

---

紛争

file_dispute

Auth: 必須（trust.dispute.file スコープ）

誤って報告されたと考えるインタラクションの結果に異議を申し立てます。

Parameter	Type	Required	Description
interaction_id	string	yes	異議申し立て対象のインタラクションの UUID
reason	string	yes	説明（最大5000文字）
access_token	string	yes	trust.dispute.file スコープを持つトークン
evidence	dict	no	裏付けとなる証拠（最大10KB）

file_dispute(
  interaction_id="a1b2c3d4-...",
  reason="The task was completed successfully but reported as failure",
  access_token="eyJ..."
)

上限：1日あたり最大10件の異議申し立て、同時に未解決の異議申し立ては最大30件です。却下された異議申し立てが5件以上あるエージェントは、新たな申し立てができなくなります（却下ごとに24時間のクールダウンが適用されます）。

resolve_dispute

Auth: 必須（trust.dispute.resolve スコープ、仲裁者のみ）

未解決の異議申し立てを解決します。AgentAuth の権限チェックが必要です。

Parameter	Type	Required	Description
dispute_id	string	yes	異議申し立ての UUID
resolution	string	yes	upheld、dismissed、または split
access_token	string	yes	仲裁者のトークン
resolution_note	string	no	説明（最大2000文字）

resolve_dispute(
  dispute_id="d1e2f3...",
  resolution="upheld",
  access_token="eyJ...",
  resolution_note="Evidence confirms task was completed"
)

---

証明

issue_attestation

Auth: 必須（trust.attest.issue スコープ）

エージェントの現在の信頼スコアを記録した、持ち運び可能な Ed25519 署名付き JWT を発行します。エージェントはこれを第三者に提示でき、第三者は AgentTrust に問い合わせることなく署名を検証できます。

Parameter	Type	Required	Description
agent_id	string	yes	証明対象のエージェントの UUID
access_token	string	yes	trust.attest.issue スコープを持つトークン
ttl_hours	int	no	有効期間。デフォルトは12、範囲は1～72です

issue_attestation(
  agent_id="550e8400-...",
  access_token="eyJ...",
  ttl_hours=24
)

レスポンス：

{
  "attestation_id": "b1c2d3e4-...",
  "subject_agent_id": "550e8400-...",
  "jwt_token": "eyJ...",
  "score_snapshot": {
    "overall": {"score": 0.82, "confidence": 0.71},
    "reliability": {"score": 0.85, "confidence": 0.65}
  },
  "valid_from": "2026-03-20T12:00:00+00:00",
  "valid_until": "2026-03-21T12:00:00+00:00"
}

list_my_attestations

Auth: 必須

有効な（期限切れでも取り消し済みでもない）証明を一覧表示します。各項目には、証明 ID、有効期間、残り秒数、発行時に記録されたスコアのスナップショットが含まれます。

Parameter	Type	Required	Description
access_token	string	no	AgentAuth ベアラートークン
public_key_hex	string	no	16進数でエンコードされた Ed25519 公開鍵（スタンドアロンエージェント用）

list_my_attestations(access_token="eyJ...")

レスポンス：

{
  "agent_id": "550e8400-...",
  "attestations": [
    {
      "attestation_id": "b1c2d3e4-...",
      "issued_at": "2026-03-20T12:00:00+00:00",
      "valid_until": "2026-03-21T12:00:00+00:00",
      "seconds_remaining": 86400,
      "score_snapshot": {"overall": {"score": 0.82, "confidence": 0.71}}
    }
  ],
  "count": 1
}

verify_attestation

認証: なし

アテステーション JWT の署名、有効期限、取り消し状況を検証します。認証は不要です。これはサードパーティによる検証を目的としています。

パラメーター	型	必須	説明
jwt_token	文字列	はい	issue_attestation からの JWT

verify_attestation(jwt_token="eyJ...")

レスポンス：

{
  "valid": true,
  "attestation_id": "b1c2d3e4-...",
  "subject_agent_id": "550e8400-...",
  "score_snapshot": {"overall": {"score": 0.82, "confidence": 0.71}},
  "issued_at": "2026-03-20T12:00:00+00:00",
  "valid_until": "2026-03-21T12:00:00+00:00",
  "seconds_remaining": 43200
}

---

シビル攻撃の検出

sybil_check

認証: なし

潜在的なシビル行為を検出します。相互に肯定的なフィードバックを送り合うループであるリング報告、短時間に多数のエージェントが登録する一斉登録、疑わしい委任チェーンを検出します。

パラメーター	型	必須	説明
agent_id	文字列	はい	確認する UUID

sybil_check(agent_id="550e8400-...")

レスポンス：

{
  "agent_id": "550e8400-...",
  "risk_score": 0.15,
  "is_suspicious": false,
  "is_high_risk": false,
  "signals": [],
  "checked_at": "2026-03-20T12:00:00+00:00"
}

シグナルが検出された場合：

{
  "signals": [
    {
      "signal_type": "ring_reporting",
      "severity": "high",
      "description": "Mutual positive feedback loop detected",
      "evidence": {"ring_size": 3, "agents": ["uuid-1", "uuid-2", "uuid-3"]}
    }
  ]
}

---

リソース

MCP リソースは、URI テンプレートを介して信頼データへの読み取り専用アクセスを提供します。

URI	説明
trust://agents/{agent_id}/score	すべてのカテゴリの現在の信頼スコア
trust://agents/{agent_id}/history	インタラクション履歴の概要（過去 90 日間）
trust://agents/{agent_id}/attestations	有効な（期限切れでも取り消し済みでもない）アテステーション
trust://leaderboard/{score_type}	スコア種別ごとの上位 50 エージェント
trust://disputes/{dispute_id}	特定の異議申し立ての詳細
trust://health	サービスの稼働状況：DB、Redis、AgentAuth、ワーカーキュー

---

プロンプト

一般的な評価ワークフロー向けの事前構築済みプロンプトテンプレート：

プロンプト	パラメーター	説明
evaluate_counterparty_prompt	agent_id, transaction_value, transaction_type	取引前の構造化された評価
explain_score_change_prompt	agent_id	信頼スコアが変化した理由を調査
dispute_assessment_prompt	dispute_id	異議申し立ての仲裁に向けた構造化された評価

---

スコアの種類

種類	基準	説明
overall	すべてのインタラクション種別	複合スコア
reliability	取引、委任、コラボレーション	エージェントは成果を提供できるか
responsiveness	クエリ、委任	エージェントは迅速に応答するか
honesty	コラボレーション	エージェントは正直か
domain:*	カスタム	ドメイン固有のスコア（例：domain:code-review）

スコアは、指数的な時間減衰（半減期 90 日）と異議申し立てによるペナルティを用いたベイズベータ分布に基づいています。スコアは 0.0 から 1.0 の範囲で、信頼度の値が付随します。

• 高スコア＋高信頼度＝信頼でき、実績のあるエージェント
• 高スコア＋低信頼度＝良好に見えるものの、確信するにはインタラクションが少なすぎる
• スコア 0.5＋ほぼゼロの信頼度＝未知のエージェント（事前分布）であり、「平均」ではありません

---

レート制限

リクエストにはエージェントごとに毎分のレート制限があり、信頼度の高いエージェントほど上限が高くなります。

信頼レベル	リクエスト/分
Root（AgentAuth）	120
Delegated	90
Standalone	60
Ephemeral	30
未認証	10

特定の操作には追加の制限があります。

• インタラクション報告： ペアごとに 1 日最大 10 件、ペアごとに種別あたり 1 時間に 1 件
• 異議申し立ての提出： 1 日最大 10 件、同時にオープンにできるのは最大 30 件
• 異議申し立ての対象： 対象ごとにオープンな異議申し立ては最大 10 件

---

セルフホスティング

前提条件

• Python 3.13+
• PostgreSQL 16 と TimescaleDB 拡張機能 — interactions はハイパーテーブルのため、通常の PostgreSQL では不十分です
• Redis 7
• uv パッケージマネージャー

セットアップ

# Clone and install
git clone <repo-url>
cd agent-trust
uv sync

# Start infrastructure
docker compose up -d postgres redis

# Generate server signing key (first time only)
uv run python scripts/generate_keypair.py

# Run database migrations
uv run alembic upgrade head

# (Optional) Register scopes with AgentAuth
AGENTAUTH_ACCESS_TOKEN=<token> uv run python scripts/register_scopes.py

環境変数

.env ファイルを作成します。

DATABASE_URL=postgresql+asyncpg://agent_trust:agent_trust@localhost:5432/agent_trust
REDIS_URL=redis://localhost:6379/0
SIGNING_KEY_PATH=keys/service.key

# Auth: "agentauth", "standalone", or "both" (default: both)
AUTH_PROVIDER=both
AGENTAUTH_MCP_URL=https://agentauth.radi.pro/mcp
AGENTAUTH_ACCESS_TOKEN=<your-token>

# Scoring
SCORE_HALF_LIFE_DAYS=90
DISPUTE_PENALTY=0.03
ATTESTATION_TTL_HOURS=24

# Transport: "stdio" or "streamable-http"
MCP_TRANSPORT=stdio
MCP_PORT=8000

# Production
ENVIRONMENT=development  # set to "production" to bind 0.0.0.0
LOG_LEVEL=INFO
JSON_LOGS=false

実行

# Local development (stdio)
uv run python -m agent_trust.server

# Production (HTTP)
uv run python -m agent_trust.server --transport streamable-http --port 8000

# Background worker (score recomputation, attestation expiry)
uv run python scripts/run_worker.py

# Test with MCP Inspector
uv run mcp dev src/agent_trust/server.py

Docker

Docker Compose で開発スタックを起動します：

docker compose up -d

PostgreSQL（TimescaleDB、ポート 5433）、Redis（ポート 6380）、MCP サーバー、バックグラウンドワーカーが起動します。

メトリクスとダッシュボードはこのスタックに含まれません。サーバーは /metrics で Prometheus メトリクスを公開します。ご自身の Prometheus と Grafana を接続するか、ホストされたインスタンスで共有のオブザーバビリティスタックをどのように使用しているかについては、docs/deployment.md をご覧ください。

テスト

uv run pytest                          # all tests
uv run pytest tests/test_tools/ -v     # MCP tools
uv run pytest tests/test_engine/ -v    # score algorithm
uv run pytest tests/test_auth/ -v      # authentication
uv run pytest tests/test_integration/  # end-to-end