trc-8004-sdk 0.1.0b1

TRC-8004 Agent SDK for TRON - Agent identity, reputation, and validation

TRC-8004 Agent SDK

去中心化 Agent 协作的 Python SDK，实现 ERC-8004 (Trustless Agent Protocol) 规范。

特性

• 🔗 多链支持：抽象的 Adapter 架构，当前支持 TRON，可扩展 EVM 链
• 🔄 自动重试：可配置的指数退避重试策略
• 🛡️ 类型安全：完整的类型注解和 Pydantic 校验
• 📝 详细日志：结构化日志便于调试
• ⚡ 异步支持：同时提供同步和异步 API

安装

# 使用 uv
uv add trc-8004-sdk

# 使用 pip
pip install trc-8004-sdk

CLI 工具

安装后可使用 trc8004 命令行工具：

# 创建新 Agent 项目
trc8004 init MyAgent
trc8004 init MyAgent --port 8200 --tags "swap,defi"

# 测试 Agent 连通性
trc8004 test --url http://localhost:8100

# 注册 Agent 到链上
trc8004 register --token-uri https://example.com/agent.json --name MyAgent

创建 Agent 项目示例

$ trc8004 init MySwapAgent --port 8200 --tags "swap,defi"

✅ Agent 项目创建成功!

📁 myswapagent/
   ├── app.py           # Agent 主程序
   ├── pyproject.toml   # 项目配置
   ├── .env.example     # 环境变量模板
   ├── README.md        # 文档
   └── tests/           # 测试

🚀 下一步:
   cd myswapagent
   uv sync
   python app.py

快速开始

from sdk import AgentSDK

# 初始化 SDK
sdk = AgentSDK(
    private_key="your_hex_private_key",
    rpc_url="https://nile.trongrid.io",
    network="tron:nile",
    identity_registry="TIdentityRegistryAddress",
    validation_registry="TValidationRegistryAddress",
    reputation_registry="TReputationRegistryAddress",
)

# 注册 Agent
tx_id = sdk.register_agent(
    token_uri="https://example.com/agent.json",
    metadata=[{"key": "name", "value": "MyAgent"}],
)
print(f"Agent registered: {tx_id}")

# 构建订单承诺
commitment = sdk.build_commitment({
    "asset": "TRX/USDT",
    "amount": 100.0,
    "slippage": 0.01,
})

核心功能

1. 身份注册 (IdentityRegistry)

# 方式 1: 使用 token_uri 注册
tx_id = sdk.register_agent(
    token_uri="https://example.com/agent.json",
    metadata=[
        {"key": "name", "value": "MyAgent"},
        {"key": "version", "value": "1.0.0"},
    ],
)

# 方式 2: 从 agent-card.json 自动提取 metadata
import json
with open(".well-known/agent-card.json") as f:
    card = json.load(f)

metadata = AgentSDK.extract_metadata_from_card(card)
# metadata 包含: name, description, version, url, skills, tags, endpoints
tx_id = sdk.register_agent(metadata=metadata)

# 更新元数据
tx_id = sdk.update_metadata(
    agent_id=1,
    key="description",
    value="Updated description",
)

2. 验证请求 (ValidationRegistry)

# 发起验证请求
tx_id = sdk.validation_request(
    validator_addr="TValidatorAddress",
    agent_id=1,
    request_uri="ipfs://QmXxx...",
    request_hash="0x" + "aa" * 32,
)

# 提交验证响应（验证者调用）
tx_id = sdk.validation_response(
    request_hash="0x" + "aa" * 32,
    response=95,  # 0-100 评分
    response_uri="ipfs://QmYyy...",
)

3. 信誉反馈 (ReputationRegistry)

# 提交信誉反馈
tx_id = sdk.submit_reputation(
    agent_id=1,
    score=95,
    tag1="0x" + "11" * 32,  # 可选标签
    feedback_auth="0x...",   # Agent 提供的授权签名
)

4. 签名构建

# 构建 A2A 请求签名
signature = sdk.build_a2a_signature(
    action_commitment="0x...",
    timestamp=int(time.time()),
    caller_address="TCallerAddress",
)

# 构建反馈授权
feedback_auth = sdk.build_feedback_auth(
    agent_id=1,
    client_addr="TClientAddress",
    index_limit=10,
    expiry=int(time.time()) + 3600,
    chain_id=None,  # 自动解析
    identity_registry="TIdentityRegistry",
)

5. 请求构建辅助

# 市价单报价请求
quote_req = sdk.build_market_order_quote_request(
    asset="TRX/USDT",
    amount=100.0,
    slippage=0.01,
)

# X402 执行请求
execute_req = sdk.build_x402_execute_request(
    action_commitment="0x...",
    order_params={"asset": "TRX/USDT", "amount": 100.0},
    payment_tx_hash="0x...",
    timestamp=int(time.time()),
    caller_address="TCallerAddress",
)

重试配置

SDK 提供可配置的重试策略：

from sdk import AgentSDK, RetryConfig, AGGRESSIVE_RETRY_CONFIG

# 使用预定义配置
sdk = AgentSDK(
    private_key="...",
    retry_config=AGGRESSIVE_RETRY_CONFIG,  # 5 次重试
)

# 自定义配置
custom_config = RetryConfig(
    max_attempts=3,
    base_delay=1.0,
    max_delay=30.0,
    exponential_base=2.0,
    jitter=True,
)
sdk = AgentSDK(private_key="...", retry_config=custom_config)

预定义配置：

• DEFAULT_RETRY_CONFIG: 3 次重试，1s 基础延迟
• AGGRESSIVE_RETRY_CONFIG: 5 次重试，0.5s 基础延迟
• CONSERVATIVE_RETRY_CONFIG: 2 次重试，2s 基础延迟
• NO_RETRY_CONFIG: 不重试

异常处理

SDK 提供细粒度的异常类型：

from sdk import (
    SDKError,
    ContractCallError,
    TransactionFailedError,
    RetryExhaustedError,
    InsufficientEnergyError,
)

try:
    tx_id = sdk.register_agent(token_uri="...")
except InsufficientEnergyError:
    print("账户能量不足，请充值")
except RetryExhaustedError as e:
    print(f"重试耗尽: {e.last_error}")
except ContractCallError as e:
    print(f"合约调用失败: {e.code} - {e.details}")
except SDKError as e:
    print(f"SDK 错误: {e}")

异常层级：

SDKError
├── ConfigurationError
│   ├── MissingContractAddressError
│   ├── InvalidPrivateKeyError
│   └── ChainIdResolutionError
├── NetworkError
│   ├── RPCError
│   ├── TimeoutError
│   └── RetryExhaustedError
├── ContractError
│   ├── ContractCallError
│   ├── ContractFunctionNotFoundError
│   ├── TransactionFailedError
│   └── InsufficientEnergyError
├── SignatureError
│   ├── InvalidSignatureError
│   └── SignerNotAvailableError
├── DataError
│   ├── InvalidAddressError
│   ├── InvalidHashError
│   ├── SerializationError
│   └── DataLoadError
└── ValidationError
    ├── RequestHashMismatchError
    ├── FeedbackAuthExpiredError
    └── FeedbackAuthInvalidError

HTTP 客户端

AgentClient

智能 HTTP 客户端，自动解析 Agent 元数据中的端点：

from sdk import AgentClient

client = AgentClient(
    metadata=agent_metadata,  # 从 Central Service 获取
    base_url="https://agent.example.com",
)

# 自动解析端点并发送请求
response = client.post("quote", {"asset": "TRX/USDT", "amount": 100})

AgentProtocolClient

Agent Protocol 标准客户端：

from sdk import AgentProtocolClient

client = AgentProtocolClient(base_url="https://agent.example.com")

# 创建任务并执行
result = client.run({
    "skill": "market_order",
    "params": {"asset": "TRX/USDT", "amount": 100},
})

链工具

from sdk import load_request_data, fetch_event_logs

# 加载请求数据（支持 file://, ipfs://, http://）
data = load_request_data("ipfs://QmXxx...")

# 获取链上事件
events = fetch_event_logs(
    client=tron_client,
    contract_address="TValidationRegistry",
    event_name="ValidationRequest",
    from_block=1000000,
    to_block=1001000,
)

扩展多链支持

SDK 使用 Adapter 模式，可轻松扩展其他链：

from sdk import ContractAdapter, Signer

class EVMContractAdapter(ContractAdapter):
    def __init__(self, rpc_url: str, ...):
        from web3 import Web3
        self.w3 = Web3(Web3.HTTPProvider(rpc_url))
    
    def send(self, contract: str, method: str, params: list, signer: Signer) -> str:
        # EVM 交易逻辑
        ...

class EVMSigner(Signer):
    def __init__(self, private_key: str):
        from eth_account import Account
        self.account = Account.from_key(private_key)
    
    def sign_message(self, payload: bytes) -> str:
        # EIP-191 签名
        ...

环境变量

变量	说明	默认值
TRON_RPC_URL	TRON RPC 节点	https://nile.trongrid.io
TRON_NETWORK	网络标识	tron:nile
IDENTITY_REGISTRY	IdentityRegistry 地址	-
VALIDATION_REGISTRY	ValidationRegistry 地址	-
REPUTATION_REGISTRY	ReputationRegistry 地址	-
TRON_FEE_LIMIT	交易费用上限 (sun)	10000000
IPFS_GATEWAY_URL	IPFS 网关	https://ipfs.io/ipfs

开发

# 安装依赖
uv sync

# 运行测试
uv run pytest

# 类型检查
uv run mypy src/sdk

License

MIT