AgentTrust

AgentTrust

面向 AI Agent 的声誉与信任评分服务，完全以 MCP 服务的形式提供。在交易前评估交易对手、报告交互结果、签发可移植的信任凭证，并检测 Sybil 攻击。

目录

• 快速入门
• 连接到 MCP 服务
• 身份验证
• 工具参考
  • 发现
  • Agent 管理
    • 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
  • Sybil 检测
• 资源
• 提示词
• 评分类型
• 速率限制
• 自行托管

---

快速入门

1. 连接到 MCP 服务

将 AgentTrust 添加到 MCP 客户端配置中：

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

或者通过 stdio 进行本地开发：

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

2. 注册你的 Agent

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 支持两种 MCP 传输方式：

传输方式	用途	端点
Streamable HTTP	远程 Agent、生产环境	https://agent-trust.radi.pro/mcp
stdio	本地开发、MCP Inspector	uv run python -m agent_trust.server

---

身份验证

AgentTrust 支持两种身份验证方式。许多工具无需身份验证即可使用，但报告交互、提交争议和签发证明时需要身份验证。

AgentAuth（首选）

从 AgentAuth 获取 bearer 令牌，并将其作为 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()

---

Agent 管理

register_agent

认证： 无

在信任网络中注册新 Agent。有三种方式：

1. AgentAuth —— 传入 AgentAuth 提供的 access_token
2. 独立注册 —— 传入自己的 public_key_hex（十六进制编码的 Ed25519 公钥）
3. 自动生成 —— 两者都不传入，系统会为你生成密钥对

参数	类型	必填	描述
display_name	string	否	易读的名称（最多 200 个字符）
capabilities	list[string]	否	标签，例如 ["search", "code-review"]（最多 50 个）
metadata	dict	否	任意键值数据（最多 10KB）
access_token	string	否	AgentAuth 不记名令牌
public_key_hex	string	否	十六进制编码的 Ed25519 公钥

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

generate_agent_token

认证： 无（直接使用私钥）

为独立 Agent 生成签名的 JWT 访问令牌。

参数	类型	必填	描述
agent_id	string	是	register_agent 返回的 UUID
private_key_hex	string	是	64 位十六进制字符，即 Ed25519 私钥
ttl_minutes	int	否	令牌有效期，默认 60，最长 1440 分钟

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

whoami

认证： 必需

检查你的身份、当前信任分数和作用域。

参数	类型	必填	描述
access_token	string	否	AgentAuth 不记名令牌
public_key_hex	string	否	十六进制编码的公钥

whoami(access_token="eyJ...")

get_agent_profile

认证： 无（已认证的调用可获取额外详情）

获取任意 Agent 的公开资料。

参数	类型	必填	描述
agent_id	string	是	要查询的 UUID
access_token	string	否	用于获取额外详情

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

search_agents

认证： 无

按信任分数、能力和交互次数搜索 Agent。

参数	类型	必填	描述
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 身份，并合并交互历史。关联后的规范 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 bearer 令牌
public_key_hex	string	是	独立 Agent 的十六进制编码 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

认证： 必需

一次调用即可获取状态快照，汇总身份、信任评分、待确认数量和有效证明。适用于仪表板或运行状况检查。

参数	类型	必需	描述
access_token	string	否	AgentAuth bearer 令牌
public_key_hex	string	否	十六进制编码的 Ed25519 公钥（独立 Agent）

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）

在交易前评估 Agent 的主要工具。返回评分（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

认证： 无

一次调用即可检查最多 20 个 Agent 的信任评分。

参数	类型	必需	描述
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 进行并列排名。

参数	类型	必需	描述
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 范围）

报告与另一个 Agent 交互的结果。双方都应提交报告以相互确认——单方面报告的权重较低。

参数	类型	必需	描述
counterparty_id	string	是	另一方 Agent 的 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 十六进制哈希（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

**认证：**必需（trust.report 权限范围）

确认对方的交互报告。此操作会创建双方确认，从而提高该报告在评分计算中的权重。

参数	类型	必填	描述
interaction_id	string	是	来自其他 Agent 的 report_interaction 的 UUID
outcome	string	是	你的看法：success、failure、timeout 或 partial
access_token	string	是	具有 trust.report 权限范围的令牌
context	dict	否	从你的角度提供的其他背景信息

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

list_pending_confirmations

**认证：**必需

列出其他 Agent 报告、等待你确认的交互。

参数	类型	必填	描述
access_token	string	是	你的访问令牌
since_days	int	否	回溯时间范围，默认值为 30，最大值为 365
limit	int	否	结果上限，默认值为 50，最大值为 200

list_pending_confirmations(access_token="eyJ...")

get_interaction_history

**认证：**必需

获取某个 Agent 的交互历史记录。

参数	类型	必填	描述
agent_id	string	是	UUID
interaction_type	string	否	按类型筛选
outcome	string	否	按结果筛选
since_days	int	否	回溯时间范围，默认值为 90，最大值为 365
limit	int	否	结果上限，默认值为 50，最大值为 200
access_token	string	是	你的访问令牌

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

---

争议

file_dispute

**认证：**必需（trust.dispute.file 权限范围）

对你认为报告有误的交互结果提出异议。

参数	类型	必填	描述
interaction_id	string	是	存在争议的交互的 UUID
reason	string	是	说明理由（最多 5000 个字符）
access_token	string	是	具有 trust.dispute.file 权限范围的令牌
evidence	dict	否	支持性证据（最大 10 KB）

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

限制：每天最多提出 10 项争议，同时最多有 30 项未解决的争议。被驳回的争议达到 5 项或以上的 Agent 将被禁止提出新争议（每次驳回后冷却 24 小时）。

resolve_dispute

**认证：**必需（trust.dispute.resolve 权限范围，仅限仲裁员）

解决一项未解决的争议。需要通过 AgentAuth 权限检查。

参数	类型	必填	描述
dispute_id	string	是	争议的 UUID
resolution	string	是	upheld、dismissed 或 split
access_token	string	是	仲裁员的令牌
resolution_note	string	否	说明理由（最多 2000 个字符）

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

---

证明

issue_attestation

**认证：**必需（trust.attest.issue 权限范围）

签发一个可移植的 Ed25519 签名 JWT，用于记录某个 Agent 当前的信任评分。该 Agent 可以向第三方出示此令牌，第三方无需查询 AgentTrust 即可验证签名。

参数	类型	必填	描述
agent_id	string	是	要证明的 Agent 的 UUID
access_token	string	是	具有 trust.attest.issue 权限范围的令牌
ttl_hours	int	否	有效期，默认值为 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

**认证：**必需

列出你的有效证明（未过期且未撤销）。每个条目都包含证明 ID、有效期、剩余秒数，以及签发时记录的评分快照。

参数	类型	必填	描述
access_token	string	否	AgentAuth Bearer 令牌
public_key_hex	string	否	十六进制编码的 Ed25519 公钥（独立 Agent）

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 检测

sybil_check

身份验证： 无

检测潜在的女巫行为：环状报告（相互给予正面反馈的循环）、突发注册（短时间内注册大量 Agent）以及可疑的委托链。

参数	类型	必填	说明
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 个 Agent
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	交易、委托、协作	Agent 是否履约？
responsiveness	查询、委托	Agent 是否及时响应？
honesty	协作	Agent 是否诚实？
domain:*	自定义	特定领域的分数（例如，domain:code-review）

分数采用带指数时间衰减（半衰期为 90 天）和争议惩罚的贝叶斯 Beta 分布。分数范围为 0.0 至 1.0，并附带置信度：

• 高分 + 高置信度 = 值得信任、信誉已确立的 Agent
• 高分 + 低置信度 = 表现不错，但交互次数太少，尚无法确定
• 0.5 分 + 接近零的置信度 = 未知 Agent（先验值），而非“平均水平”

---

速率限制

请求按每个 Agent 每分钟进行限流；信任度越高，限额越高：

信任级别	请求数/分钟
Root（AgentAuth）	120
已委托	90
独立	60
临时	30
未经身份验证	10

特定操作的其他限制：

• 交互报告： 每对每天最多 10 次，每对每种类型每小时 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