lucid-agents-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lucid Agents SDK

TypeScript/Bun framework for building, monetizing, and verifying AI agents.

用于构建、变现和验证AI Agent的TypeScript/Bun框架。

Packages

软件包

@lucid-agents/core - Protocol-agnostic agent runtime with extension system
@lucid-agents/http - HTTP extension for request/response handling
@lucid-agents/identity - ERC-8004 identity and trust layer
@lucid-agents/payments - x402 payment utilities with bi-directional tracking
@lucid-agents/analytics - Payment analytics and reporting
@lucid-agents/wallet - Wallet SDK for agent and developer wallets
@lucid-agents/a2a - A2A Protocol client for agent-to-agent communication
@lucid-agents/ap2 - AP2 (Agent Payments Protocol) extension
@lucid-agents/hono - Hono HTTP server adapter
@lucid-agents/express - Express HTTP server adapter
@lucid-agents/tanstack - TanStack Start adapter
@lucid-agents/cli - CLI for scaffolding new agent projects

Tech Stack: Bun (Node.js 20+ compatible), TypeScript (ESM, strict), tsup, Bun workspaces, Changesets

@lucid-agents/core - 与协议无关的Agent运行时，带有扩展系统
@lucid-agents/http - 用于请求/响应处理的HTTP扩展
@lucid-agents/identity - ERC-8004身份与信任层
@lucid-agents/payments - 支持双向追踪的x402支付工具集
@lucid-agents/analytics - 支付分析与报告模块
@lucid-agents/wallet - 面向Agent和开发者的钱包SDK
@lucid-agents/a2a - 用于Agent间通信的A2A Protocol客户端
@lucid-agents/ap2 - AP2（Agent Payments Protocol）扩展
@lucid-agents/hono - Hono HTTP服务器适配器
@lucid-agents/express - Express HTTP服务器适配器
@lucid-agents/tanstack - TanStack Start适配器
@lucid-agents/cli - 用于快速搭建新Agent项目的CLI工具

技术栈： Bun（兼容Node.js 20+）、TypeScript（ESM，严格模式）、tsup、Bun工作区、Changesets

Architecture

架构

Extension System

扩展系统

Features are added via composable extensions:

typescript

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .use(wallets({ config: walletsFromEnv() }))
  .use(payments({ config: paymentsFromEnv() }))
  .use(identity({ config: identityFromEnv() }))
  .use(a2a())
  .build();

Extensions: http, wallets, payments, analytics, identity, a2a, ap2

通过可组合的扩展添加功能：

typescript

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .use(wallets({ config: walletsFromEnv() }))
  .use(payments({ config: paymentsFromEnv() }))
  .use(identity({ config: identityFromEnv() }))
  .use(a2a())
  .build();

扩展： http, wallets, payments, analytics, identity, a2a, ap2

Adapters

适配器

Hono (
```
@lucid-agents/hono
```
) - Lightweight, edge-compatible
Express (
```
@lucid-agents/express
```
) - Traditional Node.js/Express
TanStack Start (
```
@lucid-agents/tanstack
```
) - Full-stack React (UI or headless)

Hono (
```
@lucid-agents/hono
```
) - 轻量、兼容边缘计算
Express (
```
@lucid-agents/express
```
) - 传统Node.js/Express适配
TanStack Start (
```
@lucid-agents/tanstack
```
) - 全栈React适配（支持UI或无头模式）

Payment Networks

支付网络

Network	Type	Finality	Gas Cost
`base` / `base-sepolia`	EVM (L2)	~12s	~$0.01
`ethereum` / `sepolia`	EVM (L1)	~12min	$0.01-$10
`solana` / `solana-devnet`	Solana	~400ms	~$0.0001

EVM: EIP-712 signatures, ERC-20 tokens (USDC), 0x-prefixed addresses Solana: Ed25519 signatures, SPL tokens (USDC), Base58 addresses

网络	类型	确认时间	燃气成本
`base` / `base-sepolia`	EVM（L2）	~12秒	~$0.01
`ethereum` / `sepolia`	EVM（L1）	~12分钟	$0.01-$10
`solana` / `solana-devnet`	Solana	~400毫秒	~$0.0001

EVM： EIP-712签名、ERC-20代币（USDC）、0x前缀地址 Solana： Ed25519签名、SPL代币（USDC）、Base58地址

x402 Protocol Versions

x402协议版本

v1: Simple network names (

base

ethereum

solana

) v2 (recommended): CAIP-2 chain IDs (

eip155:8453

for Base,

eip155:1

for Ethereum)

v1 Name	v2 CAIP-2 ID	Description
`base`	`eip155:8453`	Base Mainnet
`base-sepolia`	`eip155:84532`	Base Sepolia
`ethereum`	`eip155:1`	Ethereum Mainnet
`sepolia`	`eip155:11155111`	Ethereum Sepolia

The Daydreams facilitator (

https://facilitator.daydreams.systems

) supports both v1 and v2. Use

@lucid-agents/hono@0.7.20

+ for proper x402 v2 support on Base.

v1： 简单网络名称（

base

ethereum

solana

） v2（推荐）： CAIP-2链ID（Base对应

eip155:8453

，Ethereum对应

eip155:1

）

v1名称	v2 CAIP-2 ID	描述
`base`	`eip155:8453`	Base主网
`base-sepolia`	`eip155:84532`	Base Sepolia测试网
`ethereum`	`eip155:1`	Ethereum主网
`sepolia`	`eip155:11155111`	Ethereum Sepolia测试网

Daydreams协调器（

https://facilitator.daydreams.systems

）同时支持v1和v2版本。在Base网络上使用x402 v2需要

@lucid-agents/hono@0.7.20

及以上版本。

API Quick Reference

API快速参考

Core Agent Creation

核心Agent创建

typescript

import { createAgent } from '@lucid-agents/core';
import { http } from '@lucid-agents/http';
import { z } from 'zod';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
  description: 'My first agent',
})
  .use(http())
  .build();

agent.entrypoints.add({
  key: 'greet',
  input: z.object({ name: z.string() }),
  async handler({ input }) {
    return { output: { message: `Hello, ${input.name}` } };
  },
});

typescript

import { createAgent } from '@lucid-agents/core';
import { http } from '@lucid-agents/http';
import { z } from 'zod';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
  description: 'My first agent',
})
  .use(http())
  .build();

agent.entrypoints.add({
  key: 'greet',
  input: z.object({ name: z.string() }),
  async handler({ input }) {
    return { output: { message: `Hello, ${input.name}` } };
  },
});

Hono Adapter

Hono适配器

typescript

import { createAgent } from '@lucid-agents/core';
import { http } from '@lucid-agents/http';
import { createAgentApp } from '@lucid-agents/hono';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .build();

const { app, addEntrypoint } = await createAgentApp(agent);

addEntrypoint({
  key: 'echo',
  description: 'Echo back input',
  input: z.object({ text: z.string() }),
  handler: async ctx => {
    return { output: { text: ctx.input.text } };
  },
});

export default {
  port: Number(process.env.PORT ?? 3000),
  fetch: app.fetch,
};

typescript

import { createAgent } from '@lucid-agents/core';
import { http } from '@lucid-agents/http';
import { createAgentApp } from '@lucid-agents/hono';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .build();

const { app, addEntrypoint } = await createAgentApp(agent);

addEntrypoint({
  key: 'echo',
  description: 'Echo back input',
  input: z.object({ text: z.string() }),
  handler: async ctx => {
    return { output: { text: ctx.input.text } };
  },
});

export default {
  port: Number(process.env.PORT ?? 3000),
  fetch: app.fetch,
};

Payments Extension

支付扩展

typescript

import { createAgent } from '@lucid-agents/core';
import { payments, paymentsFromEnv } from '@lucid-agents/payments';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(
    payments({
      config: {
        ...paymentsFromEnv(),
        policyGroups: [
          {
            name: 'Daily Limits',
            outgoingLimits: {
              global: { maxTotalUsd: 100.0, windowMs: 86400000 },
            },
            incomingLimits: {
              global: { maxTotalUsd: 5000.0, windowMs: 86400000 },
            },
          },
        ],
      },
      storage: { type: 'sqlite' }, // or 'in-memory' or 'postgres'
    })
  )
  .build();

typescript

import { createAgent } from '@lucid-agents/core';
import { payments, paymentsFromEnv } from '@lucid-agents/payments';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(
    payments({
      config: {
        ...paymentsFromEnv(),
        policyGroups: [
          {
            name: 'Daily Limits',
            outgoingLimits: {
              global: { maxTotalUsd: 100.0, windowMs: 86400000 },
            },
            incomingLimits: {
              global: { maxTotalUsd: 5000.0, windowMs: 86400000 },
            },
          },
        ],
      },
      storage: { type: 'sqlite' }, // 或 'in-memory' 或 'postgres'
    })
  )
  .build();

ERC-8004 Identity Registration

ERC-8004身份注册

CRITICAL: Per ERC-8004 spec,
agentURI
MUST be a URL to hosted metadata, NOT inline JSON.

Host registration file at
```
/.well-known/erc8004.json
```
Generate agent icon (512x512 PNG)
Register on-chain with the hosted URL

typescript

// WRONG - DO NOT pass inline JSON
const agentURI = JSON.stringify({ name: "Agent", ... });

// CORRECT - Pass URL to hosted registration file
const agentURI = 'https://my-agent.example.com/.well-known/erc8004.json';

Network	Registry Address
Ethereum Mainnet	`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`
Base	`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`

Full reference: ERC8004_REFERENCE.md

重要提示：根据ERC-8004规范，
agentURI
必须是指向托管元数据的URL，而非内联JSON。

托管注册文件至
```
/.well-known/erc8004.json
```
生成Agent图标（512x512 PNG格式）
链上注册时使用托管URL

typescript

// 错误示例 - 请勿传入内联JSON
const agentURI = JSON.stringify({ name: "Agent", ... });

// 正确示例 - 传入托管注册文件的URL
const agentURI = 'https://my-agent.example.com/.well-known/erc8004.json';

网络	注册合约地址
Ethereum主网	`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`
Base	`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`

完整参考：ERC8004_REFERENCE.md

Critical Requirements

关键要求

Zod v4 Required (NOT v3!)

必须使用Zod v4（禁止使用v3！）

json

{ "dependencies": { "zod": "^4.0.0" } }

Error with v3:

TypeError: z.toJSONSchema is not a function

Fix:

bun add zod@4

json

{ "dependencies": { "zod": "^4.0.0" } }

使用v3会报错：

TypeError: z.toJSONSchema is not a function

修复方案：

bun add zod@4

@lucid-agents/hono v0.7.20+ for Base x402

Base网络x402需要@lucid-agents/hono v0.7.20+版本

json

{ "dependencies": { "@lucid-agents/hono": "^0.7.20" } }

Error with older versions:

No facilitator registered for scheme: exact and network: base

Fix:

bun add @lucid-agents/hono@latest

json

{ "dependencies": { "@lucid-agents/hono": "^0.7.20" } }

旧版本会报错：

No facilitator registered for scheme: exact and network: base

修复方案：

bun add @lucid-agents/hono@latest

Required Environment Variables

必需环境变量

bash

PAYMENTS_RECEIVABLE_ADDRESS=0xYourWalletAddress  # required
FACILITATOR_URL=https://facilitator.daydreams.systems  # required
NETWORK=base  # required (or base-sepolia, ethereum, solana, etc.)

bash

PAYMENTS_RECEIVABLE_ADDRESS=0xYourWalletAddress  # 必填
FACILITATOR_URL=https://facilitator.daydreams.systems  # 必填
NETWORK=base  # 必填（或base-sepolia, ethereum, solana等）

Bun Server Export Format

Bun服务器导出格式

typescript

// Correct - Bun auto-serves this
export default {
  port: Number(process.env.PORT ?? 3000),
  fetch: app.fetch,
};

Do NOT call

Bun.serve()

explicitly -- causes

EADDRINUSE

typescript

// 正确格式 - Bun会自动托管
export default {
  port: Number(process.env.PORT ?? 3000),
  fetch: app.fetch,
};

请勿显式调用

Bun.serve()

——会导致

EADDRINUSE

错误。

Minimal Working Example

最小可运行示例

typescript

import { createAgent } from '@lucid-agents/core';
import { http } from '@lucid-agents/http';
import { createAgentApp } from '@lucid-agents/hono';
import { payments, paymentsFromEnv } from '@lucid-agents/payments';
import { z } from 'zod';  // Must be zod v4!

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
  description: 'My agent',
})
  .use(http())
  .use(payments({ config: paymentsFromEnv() }))
  .build();

const { app, addEntrypoint } = await createAgentApp(agent);

addEntrypoint({
  key: 'hello',
  description: 'Say hello',
  input: z.object({ name: z.string() }),
  price: { amount: 0 },  // Free endpoint
  handler: async (ctx) => {
    return { output: { message: `Hello, ${ctx.input.name}!` } };
  },
});

const port = Number(process.env.PORT ?? 3000);
console.log(`Agent running on port ${port}`);

export default { port, fetch: app.fetch };

typescript

import { createAgent } from '@lucid-agents/core';
import { http } from '@lucid-agents/http';
import { createAgentApp } from '@lucid-agents/hono';
import { payments, paymentsFromEnv } from '@lucid-agents/payments';
import { z } from 'zod';  // 必须是zod v4！

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
  description: 'My agent',
})
  .use(http())
  .use(payments({ config: paymentsFromEnv() }))
  .build();

const { app, addEntrypoint } = await createAgentApp(agent);

addEntrypoint({
  key: 'hello',
  description: 'Say hello',
  input: z.object({ name: z.string() }),
  price: { amount: 0 },  // 免费端点
  handler: async (ctx) => {
    return { output: { message: `Hello, ${ctx.input.name}!` } };
  },
});

const port = Number(process.env.PORT ?? 3000);
console.log(`Agent running on port ${port}`);

export default { port, fetch: app.fetch };

Minimal package.json

最小package.json示例

json

{
  "name": "my-agent",
  "type": "module",
  "scripts": {
    "dev": "bun run --hot src/index.ts",
    "start": "bun run src/index.ts"
  },
  "dependencies": {
    "@lucid-agents/core": "latest",
    "@lucid-agents/http": "latest",
    "@lucid-agents/hono": "latest",
    "@lucid-agents/payments": "latest",
    "hono": "^4.0.0",
    "zod": "^4.0.0"
  }
}

json

{
  "name": "my-agent",
  "type": "module",
  "scripts": {
    "dev": "bun run --hot src/index.ts",
    "start": "bun run src/index.ts"
  },
  "dependencies": {
    "@lucid-agents/core": "latest",
    "@lucid-agents/http": "latest",
    "@lucid-agents/hono": "latest",
    "@lucid-agents/payments": "latest",
    "hono": "^4.0.0",
    "zod": "^4.0.0"
  }
}

Entrypoint Path Convention

入口点路径约定

Invoke:
```
POST /entrypoints/{key}/invoke
```
Stream:
```
POST /entrypoints/{key}/stream
```
Health:
```
GET /health
```
Landing:
```
GET /
```
(HTML page)

调用：
```
POST /entrypoints/{key}/invoke
```
流式传输：
```
POST /entrypoints/{key}/stream
```
健康检查：
```
GET /health
```
着陆页：
```
GET /
```
（HTML页面）

Resources

资源

AGENTS.md - Full AI coding guide
CONTRIBUTING.md - Contribution guidelines
ERC-8004 Specification
x402 Protocol
A2A Protocol
SDK Reference - Monorepo structure, commands, coding standards, additional adapters

AGENTS.md - 完整AI编码指南
CONTRIBUTING.md - 贡献指南
ERC-8004规范
x402协议
A2A协议
SDK参考 - 单体仓库结构、命令、编码规范、额外适配器