Garl-Protocol

重要

已于 2026 年 9 月 24 日归档。 GARL 已停止维护，托管服务（garl.ai、api.garl.ai）不再接受 Agent、跟踪记录或回执。代码仍以 Apache-2.0 许可证提供。锚定在 Base 主网的 12 份回执仍可在 garl.ai/anchors 验证。联系方式：[email protected]。恢复说明：docs/runbooks/sunset.md。

GARL Protocol

证明你的 AI Agent 获得了哪些操作授权，以及它实际执行了哪些操作。

能力令牌为 Agent 设置严格限制——消费上限、商户允许列表、副作用类别、有效期——而委派令牌只能收紧其父令牌的限制，不能放宽。
每项操作都会生成一份由 ECDSA-secp256k1 签名、绑定到授权令牌的操作回执，并通过 Merkle 锚定在 Base 主网上；无需信任 GARL，即可离线验证。

添加你的 Agent · 锚定链 · 网站 · 文档 · 实时回执 · 立即试用

---

---

立即试用

路径 A — 面向 Agent（SDK / MCP）

使用 Claude Desktop 或 Cursor（MCP）

将以下内容添加到 Claude Desktop 配置（claude_desktop_config.json）或 Cursor MCP 设置中：

{
  "mcpServers": {
    "garl": {
      "command": "npx",
      "args": ["-y", "@garl-protocol/mcp-server"]
    }
  }
}

完成后，AI 助手中即可使用 29 个命名工具（包括 garl_verify_batch 等批量变体）：回执、Trust Vector 查询、能力令牌（签发/验证/撤销）、Capability Gate 预检、UETA §10(b) 撤销操作等。

使用 curl（无需安装）

# Check an agent's trust score
curl -s "https://api.garl.ai/api/v1/trust/verify?agent_id=5872ce17-5718-4980-ade3-e51c9556fb53" | python3 -m json.tool

# Find the most trusted coding agent
curl -s "https://api.garl.ai/api/v1/trust/route?category=coding&min_tier=silver" | python3 -m json.tool

# See the live leaderboard
curl -s "https://api.garl.ai/api/v1/leaderboard?limit=5" | python3 -m json.tool

使用 Python

pip install garl-protocol

import garl

garl.init("your_api_key", "your_agent_uuid")
garl.log_action("Analyzed dataset", "success", category="data")

result = garl.is_trusted("target_agent_uuid", min_score=60)
if result["trusted"]:
    print(f"Safe to delegate — score: {result['score']}/100")

使用 JavaScript

npm install @garl-protocol/sdk

import { init, logAction, isTrusted } from "@garl-protocol/sdk";

init("your_api_key", "your_agent_uuid", "https://api.garl.ai/api/v1");
await logAction("Generated REST API", "success", { category: "coding" });

const result = await isTrusted("target_agent_uuid", { minScore: 60 });
if (result.trusted) {
  console.log(`Safe to delegate — score: ${result.score}/100`);
}

能力令牌 — 带有严格限制的授权

# Issue a scoped token for your agent (owner API key required)
curl -s -X POST https://api.garl.ai/api/v1/capability/issue \
  -H "x-api-key: $GARL_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-uuid",
    "scope": "payment:stripe.com",
    "side_effect_class": "reversible",
    "spend_limit_usd": 50,
    "merchant_allowlist": ["stripe.com"],
    "expires_in_seconds": 3600
  }' | python3 -m json.tool

# Anyone can verify a token — no auth, no account
curl -s -X POST https://api.garl.ai/api/v1/capability/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "<the JWT-form token>"}' | python3 -m json.tool

委派的子令牌只能收紧父令牌的限制（降低消费上限、 使用父令牌允许列表的子集、采用范围相同或更窄的权限，以及设置相同或更早的到期时间）——签发时强制执行， 并在验证时逐条重新检查令牌链。完整线路格式： protocol/spec/capability-token-v0.1.md。

路径 B — 面向代码（GitHub Action，只需 5 行 YAML）

为拉取请求中的每个 AI 编写的提交签名。

# .github/workflows/garl-receipt.yml
name: GARL Receipt
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  sign:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write, checks: write }
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: Garl-Protocol/[email protected]
        with:
          garl-api-key: ${{ secrets.GARL_API_KEY }}
          garl-agent-id: ${{ secrets.GARL_AGENT_ID }}

每个 PR 都会收到一条滚动更新的 GARL 回执评论和一项提示性检查：

🔐 GARL Verified AI Code
├── Model: claude-opus-4-6
├── Tool: Claude Code
├── Files touched: 12
├── Duration: 4m 12s
├── Signed: ECDSA-secp256k1 ✓
└── Receipt: https://garl.ai/r/a8f3c2d1

设置指南：Garl-Protocol/garl-receipt-action · 在线介绍页：garl.ai/for-code。

---

收据——可直接粘贴的每条执行轨迹证明

每条提交的执行轨迹都会获得一个公开可分享的 收据 URL： https://garl.ai/r/{short} —— 一张加密证明卡片（Agent、层级、任务、时长、SHA-256 哈希、ECDSA 签名），附带 Open Graph 图片，可在 Slack、Twitter/X、GitHub PR 和 LinkedIn 中以丰富预览形式显示。

curl -s https://api.garl.ai/api/v1/verify/6ff83db8 | python3 -m json.tool
#  → receipt_url: https://garl.ai/r/6ff83db8

SDK 会在每次 log_action / verify 的返回结果中提供 receipt_url / receiptUrl，并提供 client.receipt(hash) 快捷方法。MCP 工具 garl_receipt 可将任意短哈希或完整哈希解析为可直接粘贴的 URL。

GitHub Action——为每次 AI 编写的提交签名

将 Garl-Protocol/garl/integrations/github-action-receipt 添加到你的 PR 工作流中。它会检测 Claude Code、Cursor、GitHub Copilot、Aider 和 Codex 的共同作者尾注，为每个符合条件的提交提交一条签名执行轨迹，并发布滚动更新的 PR 评论和信息性检查，其中包含收据 URL：

- uses: Garl-Protocol/garl/integrations/github-action-receipt@main
  with:
    garl-api-key: ${{ secrets.GARL_API_KEY }}
    garl-agent-id: ${{ secrets.GARL_AGENT_ID }}

完整设置说明见 integrations/github-action-receipt。 仅上传元数据——绝不上传差异内容或源代码。

为什么选择 GARL？

问题	GARL 的解决方案
“这个 Agent 获准执行哪些操作？”	能力令牌：spend_limit_usd、merchant_allowlist、side_effect_class、过期时间——采用 Biscuit 风格的权限收窄机制（委派只能收窄权限，验证时逐链接重新检查）
“它是否遵守了这些限制？”	每份操作收据都会将 capability_request.token_hash + policy_decision 绑定到签名信封中；能力门会将低信任度的不可逆操作升级为需要人工处理
“这个 Agent 是否可靠？”	使用指数移动平均法进行五维信任评分
“我应该选择哪个 Agent？”	根据类别 + 最低认证层级进行智能路由
“我能否验证它的过往记录？”	不可变账本，包含 ECDSA 签名的执行轨迹 + 可分享的收据 URL
“它是否适配我的技术栈？”	MCP 服务 · A2A Protocol · REST API · Python 和 JS SDK · GitHub Action
“如何证明这次 AI 提交是真实的？”	GitHub Action 会为每次 AI 编写的提交发布一份签名收据
“链上 Agent 如何处理？”	兼容 ERC-8004 格式（链下）。批量收据的 Merkle 根锚定在 Base 主网上（MerkleAnchor 位于 0xBeD7EdeFbEb02be9682bCdeC5fb5D7DA28b1b6F2）。

---

兼容

Claude Desktop · Cursor · 任意 MCP 客户端 · Google A2A · ERC-8004 · REST API · Python · JavaScript · LangChain · CrewAI · AutoGen · LlamaIndex · Semantic Kernel · GitHub Actions

---

工作原理

每个 Agent 操作都会经过哈希、签名，并按五个维度评分，同时可供查询，从而建立可验证的信任记录。

Agent executes task → SHA-256 hash + ECDSA signature → 5D EMA scoring → Tier assigned → Queryable via API/MCP/A2A

┌─────────────────────────────────────────────────────────────────┐
│                        GARL Protocol                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐    │
│  │  Python   │   │   JS     │   │   MCP    │   │   A2A    │    │
│  │   SDK     │   │   SDK    │   │  Server  │   │ JSON-RPC │    │
│  └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘    │
│       │              │              │              │            │
│       └──────────────┴──────────────┴──────────────┘            │
│                          │                                      │
│                    ┌─────▼─────┐                                │
│                    │  FastAPI  │  REST + A2A + MCP              │
│                    │  Backend  │  Rate Limited + CORS            │
│                    └─────┬─────┘                                │
│                          │                                      │
│          ┌───────────────┼───────────────┐                      │
│          │               │               │                      │
│    ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐               │
│    │ Reputation│  │  Signing  │  │  Webhook  │               │
│    │  Engine   │  │  Engine   │  │  Engine   │               │
│    │ • 5D EMA  │  │ • SHA-256 │  │ • HMAC    │               │
│    │ • Tiers   │  │ • ECDSA   │  │ • Retry   │               │
│    └───────────┘  └───────────┘  └───────────┘               │
│                          │                                      │
│                    ┌─────▼─────┐                                │
│                    │ Supabase  │  PostgreSQL + RLS              │
│                    │           │  Immutable Triggers            │
│                    └───────────┘                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

ERC-8004 兼容性

GARL Protocol 以 ERC-8004 格式提供 Agent 元数据（链下）。此外，批量操作收据的 Merkle 根会锚定在 Base 主网上（MerkleAnchor 合约 0xBeD7EdeFbEb02be9682bCdeC5fb5D7DA28b1b6F2，链 ID 为 8453）。单独的收据不会写入链上；任何人都可以通过 verifyProof，根据已锚定的根验证收据是否包含在其中。

# Get ERC-8004 compatible metadata for any agent
curl -s "https://api.garl.ai/api/v1/agents/{agent_id}/erc8004" | python3 -m json.tool

# Get trust scores in ERC-8004 Reputation Registry feedback format
curl -s "https://api.garl.ai/api/v1/agents/{agent_id}/erc8004/feedback" | python3 -m json.tool

GARL 使用与 Ethereum 相同的加密曲线（ECDSA-secp256k1），因此链上系统可以原生验证信任证明。

---

文档

主题	链接
Capability Token 线格式（规范）	protocol/spec/capability-token-v0.1.md
Action Receipt 线格式（规范）	protocol/spec/action-receipt-v0.1.md
锚定操作手册（每周在 Base 上进行 Merkle 锚定）	docs/runbooks/anchoring.md
完整 API 参考（60 多个 REST 端点 + A2A + MCP）	docs/api-reference.md
MCP 服务（29 个命名工具，含批量变体）	garl.ai/docs#mcp-server
A2A 协议集成	garl.ai/docs#a2a
ERC-8004 兼容性	garl.ai/docs#erc-8004
Python 和 JS SDK	garl.ai/docs#sdks
架构与技术栈	docs/architecture.md
部署与自托管	docs/deployment.md
安全性	docs/security.md

交互式 API 浏览器：api.garl.ai/docs（Swagger） · api.garl.ai/redoc

---

现已上线

• garl.ai — 实时仪表板和实时信任动态
• 添加你的 Agent — 只需三个步骤即可连接任意 Agent（REST、SDK、MCP、GitHub Action）
• 我的 Agent — 登录（Clerk）并认领通过 API 密钥连接的 Agent，在一个地方跟踪其活动
• 注册表 — 浏览已连接的 Agent 及其经过签名、可验证的活动
• 验证 — 公开的加密轨迹验证
• Playground — 交互式 API 浏览器
• 模拟器 — 支持假设分析的 5D 信任评分计算器
• 比较 — 并排比较 Agent，并叠加雷达图
• Swagger — 完整的 OpenAPI 文档
• 锚点 — 每个 Merkle 批次及其根哈希、回执数量和 Base 交易（GET /api/v1/anchors）
• Base 上的 MerkleAnchor — 锚定在 Base 主网（链 ID 8453）上的回执批次 Merkle 根
• MCP 注册表 — 已列入，名称为 io.github.Garl-Protocol/agent-trust

---

参与贡献

GARL Protocol 基于 Apache 2.0 License 开源。欢迎贡献——请参阅 CONTRIBUTING.md 了解指南，并参阅 CODE_OF_CONDUCT.md 了解社区规范。每次提交都必须使用 DCO 签署（git commit -s）。

**要求：**后端需要 Python 3.10+（使用 PEP 604 联合类型语法）， 前端需要 Node 18+。macOS 用户请注意：系统自带的 python3 版本为 3.9， 会导致后端测试失败——请通过 pyenv / brew install [email protected] 安装 3.10+， 并显式调用（python3.12 -m pytest tests/）。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 运行测试（后端运行 python3.12 -m pytest，前端运行 npx next build）
4. 使用 DCO 签署提交更改（git commit -s -m 'Add amazing feature'）
5. 发起 Pull Request

---

权威注册中心、自托管与标识

• 权威注册中心：https://api.garl.ai — 这是唯一一个以其公钥作为 GARL Verified 状态依据的部署。公钥发布于 /.well-known/garl-keys.json。
• 支持自托管，相关说明见 docs/self-host.md。自托管部署是正式参与方，但并非权威注册中心；请参阅 GOVERNANCE.md。
• 商标政策：TRADEMARK.md。源代码采用 Apache 2.0 许可；GARL 名称和徽标是项目标识，受该政策约束。

项目决策方式、破坏性变更流程，以及仓库功能（永久采用 Apache 2.0 许可）与未来可能仅在权威注册中心提供的 Cloud 服务之间的界限，均记录于 GOVERNANCE.md。

---

许可证

Apache License 2.0 — 详情请参阅 LICENSE。