agentpassport 为多 Agent AI 系统提供基于加密身份的签名委托链和 scope 强制执行，让 Agent 间的授权从约定信任升级为可验证的加密证明。
# agentpassport
[](https://pypi.org/project/agentpassport/)
[](https://www.npmjs.com/package/@agentpassport/core)
[](LICENSE)
[](https://github.com/ceavinrufus/agentpassport/actions/workflows/ci.yml)
**多 Agent AI 系统的授权层。**
就像 IAM，但专为你的 Agent 图设计。
## 问题所在
Agent 正在向其他 Agent 委托任务。但没有人去检查这条委托链。
当 Agent A 委托给 Agent B，而 Agent B 又委托给 Agent C 时——你怎么知道 C 实际上被授权做了什么？目前，每个主流框架（LangGraph、CrewAI、AutoGen）对这个问题的回答都是：*基于约定的信任*。没有签名证明。没有 scope 强制执行。无法在中途撤销。
这不是授权。这是碰运气。
```
[Python Orchestrator] signs delegation → [TypeScript Agent] verifies before executing
↓
ScopeError: requires [write:db:customers], granted [read:db:customers] ✅
```
agentpassport 为每个 Agent 提供加密身份，在每一跳签署委托，并在 handler 运行前强制执行 scope。通过 JTI 撤销 token，Agent 就会干净地停止——无需杀掉进程，也不会产生部分状态。
## 演示
**跨 SDK 信任链** —— Python orchestrator 委托给 TypeScript Agent：
```
git clone https://github.com/ceavinrufus/agentpassport
cd agentpassport
uv run python -m demo.run_demo
```
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
agentpassport DEMO — Cross-SDK Trust Chain
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Orchestrator did:key:z6MkskpV…pks2 (Python)
TS Agent did:key:z6MkoFDL…3TZf (TypeScript)
[STEP 1] Python signs delegation JWT
scope ['read:db:customers'] ttl 3600s
[STEP 2] Python → TS: queryCustomers → 200 ✅
Auth chain verified, capability executed
[STEP 3] Python → TS: writeCustomer → 403 🛡️
ScopeError: requires [write:db:customers], granted [read:db:customers]
[STEP 4] Python revokes delegation mid-scenario
jti revoked → same request fails → 403 🛡️
[STEP 5] Auth chain trace
hop 0 jti=d77dd09a… ✅
iss z6MkskpV… (orchestrator)
sub z6MkoFDL… (ts-agent)
scope ['read:db:customers']
exp 2026-05-12T10:22:48Z
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**所有权绑定** —— 域名 + 钱包绑定，离线验证，撤销：
```
uv run python -m demo.binding_demo
```
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
agentpassport — Ownership Binding Demo
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[STEP 1] Generate agent identity
DID: did:key:z6Mkv4kj…
✅ Agent identity created
[STEP 2] Bind agent to domain 'agentpassport.fyi'
✅ Domain binding created
[STEP 3] Bind agent to Ethereum wallet
✅ Wallet binding created
[STEP 4] Assemble binding document
Document (publish at https://agentpassport.fyi/.well-known/agent-passport.json)
[STEP 5] Verify signatures offline
✅ Domain binding signature valid
✅ Wallet binding signature valid
✅ Tampered signature correctly rejected
✅ Expired binding correctly rejected
[STEP 6] Revoke wallet binding
✅ Wallet binding is now revoked
✅ Domain binding unaffected by wallet revocation
[STEP 7] Final document state
binding type=domain [active]
binding type=wallet [REVOKED]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
### 实时验证域名所有权
agentpassport.fyi 发布了其自身的 `/.well-known/agent-passport.json` —— 你现在就可以验证它：
```
$ agentpass identity verify-domain \
--did did:key:z6Mkh8UwkN88kwynM3mYke8yFXr9ax69jZKv2TCuwG7yPzbw \
--domain agentpassport.fyi
```
输出：
```
Checking https://agentpassport.fyi/.well-known/agent-passport.json ...
✓ Valid domain binding: 'agentpassport.fyi' claims did:key:z6Mkh8UwkN88kwynM3mYke8yFXr9ax69jZKv2TCuwG7yPzbw
```
## 安装
```
# Python
pip install agentpassport
# TypeScript / JavaScript
npm install @agentpassport/core
```
- [PyPI 上的 agentpassport](https://pypi.org/project/agentpassport/)
- [npm 上的 @agentpassport/core](https://www.npmjs.com/package/@agentpassport/core)
## 为什么选择 agentpassport？
| 问题 | 没有 agentpassport 时 | 有 agentpassport 时 |
|---|---|---|
| Agent 授权 | 基于约定的信任 | 加密证明 |
| Scope 强制执行 | 临时检查 | 声明 + 执行前验证 |
| 撤销 | 杀掉进程 | 通过 JTI 软停止，中途安全 |
| 跨语言 | 每次集成都需自定义 | 开箱即用的 wire 兼容性 |
## 工作原理
### 1. 加密身份
每个 Agent 都有一个 Ed25519 密钥对。其公钥成为 W3C 标准的 `did:key:` DID —— 无需中央注册表，任何人都可以验证。
```
from agentpassport import Agent
agent = Agent("my-agent")
print(agent.did) # did:key:z6Mk...
```
### 2. 签名委托（Auth 链）
信任通过一连串签名的 JWT 传递。每一跳都会缩小 scope —— Agent 永远不能授予超出其自身拥有的权限。
```
from agentpassport import sign_delegation, verify_auth_chain
# Root 签署初始 grant
token = sign_delegation(
issuer_private_key=root_priv,
issuer_did=root_did,
subject_did=agent.did,
scope=["read:db:customers"],
ttl_seconds=3600,
)
# 接收 agent 在执行前进行验证
verify_auth_chain(
auth_chain=[token],
expected_subject=agent.did,
known_public_keys={root_did: root_pub},
)
```
### 3. 执行前 Scope 声明
Capabilities 声明它们需要什么 scope。agentpassport 在 handler 运行前进行检查 —— 快速失败，无部分状态。
```
@agent.capability("query_customers", requires=["read:db:customers"])
async def handle(task: TaskEnvelope) -> dict:
# Only reached if auth chain grants read:db:customers
return {"customers": [...]}
```
### 4. 撤销
通过 JTI 撤销委托，而无需停止处理中的工作 —— Agent 会完成当前操作并在下一次操作前停止。
```
from agentpassport import InMemoryRevocationRegistry, SqliteRevocationRegistry
registry = SqliteRevocationRegistry("revocations.db")
registry.revoke(jti) # all future requests with this token fail
```
## TypeScript SDK
与 Python 实现 wire 兼容 —— 跨语言信任链开箱即用。
```
import { Agent, InMemoryRevocationRegistry, ScopeError } from "@agentpassport/core"
const agent = new Agent("ts-agent", { privateKey, revocationRegistry })
agent.trustKeys({ [orchestratorDid]: orchestratorPublicKey })
agent.capability("queryCustomers", { requires: ["read:db:customers"] }, async (task) => {
return { customers: [...] }
})
```
Python orchestrator 可以签署委托 JWT。TypeScript Agent 可以验证它。无需共享基础设施。
## Scope 格式
scope 是 `action:resource` 对：
```
["read:db:customers", "write:api:stripe", "send:email:notifications"]
```
两部分结合在一起使授权可被证明。仅有 action（`"read"`）太宽松了。仅有 resource（`"db:customers"`）是不完整的。
## 安装
```
pip install agentpassport # Python SDK
pip install agentpassport[otel] # + OpenTelemetry sink
```
```
cd packages/agentpassport-ts && npm install # TypeScript SDK
```
## 包
| 包 | 描述 |
|---------|-------------|
| [`agentpassport`](https://pypi.org/project/agentpassport/) [](https://pypi.org/project/agentpassport/) | Python 信任和授权层 |
| [`@agentpassport/core`](https://www.npmjs.com/package/@agentpassport/core) [](https://www.npmjs.com/package/@agentpassport/core) | TypeScript SDK（wire 兼容） |
| [`agentpassport-registry`](https://pypi.org/project/agentpassport-registry/) [](https://pypi.org/project/agentpassport-registry/) | 带有签名验证的可信 Agent 注册表 |
| [`agentpassport-adapters`](https://pypi.org/project/agentpassport-adapters/) [](https://pypi.org/project/agentpassport-adapters/) | MCP、REST 和 A2A 适配器 |
| [`agentpassport-cli`](https://pypi.org/project/agentpassport-cli/) [](https://pypi.org/project/agentpassport-cli/) | CLI —— 密钥生成、trace 查看器 |
## CLI
```
# 生成 keypair 和 DID
agentpass identity keygen --alias myagent
# 从 trace 中检查 auth chain
agentpass trace show --id trace_abc --file traces.jsonl
```
## 所有权绑定
Agent 可以通过在 `/.well-known/agent-passport.json` 发布签名绑定文档来证明现实世界的所有权。
```
from agentpassport import (
generate_keypair, did_from_public_key,
bind_domain, bind_wallet, BindingDocument,
verify_binding_attestation,
)
priv, pub = generate_keypair()
did = did_from_public_key(pub)
# 创建 bindings
domain_binding = bind_domain(priv[:32], did, "agentpassport.fyi")
wallet_binding = bind_wallet(priv[:32], did, "ethereum", "0xYourAddress")
# 组装并发布
doc = BindingDocument(version="1")
doc.add(domain_binding)
doc.add(wallet_binding)
print(doc.to_json()) # publish at https://agentpassport.fyi/.well-known/agent-passport.json
# 离线验证
ok = verify_binding_attestation(domain_binding) # True
```
或者使用 CLI：
```
agentpass identity bind-domain --alias myagent --domain agentpassport.fyi --output ap.json
agentpass identity bind-wallet --alias myagent --chain ethereum --address 0x... --output ap.json
agentpass identity verify-domain --did
--domain agentpassport.fyi
```
有关完整流程，请参阅[所有权绑定指南](docs/guides/ownership-binding.md)。
## 路线图
| | 功能 | 状态 |
|---|---|---|
| **授权层** | 加密 Agent 身份（`did:key:`） | ✅ 完成 |
| | 签名委托链（JWT） | ✅ 完成 |
| | Scope 强制执行 + 撤销 | ✅ 完成 |
| | Python SDK | ✅ 完成 |
| | TypeScript SDK | ✅ 完成 |
| | 跨语言 wire 兼容性 | ✅ 完成 |
| | MCP middleware 适配器 | ✅ 完成 |
| | A2A 协议适配器（入站 + 出站） | ✅ 完成 |
| **AI Passport** | 身份撤销 | ✅ 完成 |
| | 域名所有权绑定 | ✅ 完成 |
| | 钱包所有权绑定（链无关） | ✅ 完成 |
| | 去中心化 Agent 发现 | 🔜 计划中 |
| | Merkle 树撤销（可扩展，支持链上就绪） | 🔜 计划中 |
| | 人类可读的所有权声明 | 🔜 计划中 |
## 开发
```
uv sync --all-packages
uv run pytest # Python tests (173)
cd packages/agentpassport-ts && npm test # TypeScript tests (48)
uv run python -m tests.cross-sdk.generate_fixtures && \
cd tests/cross-sdk && npx tsx generate_ts_fixtures.ts # cross-SDK fixtures
```
## 贡献
欢迎提交 PR。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。
## 许可证
Apache-2.0