lucid-agents-sdk

📁 langoustine69/skills-market 📅 12 days ago

总安装量

周安装量

#41309

全站排名

安装命令

npx skills add https://github.com/langoustine69/skills-market --skill lucid-agents-sdk

Agent 安装分布

mcpjam 1

claude-code 1

replit 1

windsurf 1

zencoder 1

crush 1

Skill 文档

Lucid Agents SDK Skill

Use this skill when working with the Lucid Agents SDK – a TypeScript framework for building and monetizing AI agents.

When to Use This Skill

This skill should be activated when:

Building or modifying Lucid Agents projects
Working with agent entrypoints, payments, identity, or A2A communication
Developing in the lucid-agents monorepo
Creating new templates or CLI features
Questions about the Lucid Agents architecture or API

Project Overview

Lucid Agents is a TypeScript/Bun monorepo for building, monetizing, and verifying AI agents. It provides:

@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:

Runtime: Bun (Node.js 20+ compatible)
Language: TypeScript (ESM, strict mode)
Build: tsup
Package Manager: Bun workspaces
Versioning: Changesets

Architecture Overview

Extension System

The framework uses an extension-based architecture where features are added via composable extensions:

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();

Available Extensions:

http – HTTP request/response handling, streaming, SSE
wallets – Wallet management for agents
payments – x402 payment verification and tracking
analytics – Payment analytics and reporting
identity – ERC-8004 on-chain identity and trust
a2a – Agent-to-agent communication protocol
ap2 – Agent Payments Protocol extension

Adapter System

The framework supports multiple runtime adapters:

Hono (@lucid-agents/hono) – Lightweight HTTP server, edge-compatible
Express (@lucid-agents/express) – Traditional Node.js/Express server
TanStack Start (@lucid-agents/tanstack) – Full-stack React with dashboard (UI) or API-only (headless)

Templates are adapter-agnostic and work with any compatible adapter.

Payment Networks

EVM Networks:

base – Base mainnet (L2, low cost)
base-sepolia – Base Sepolia testnet
ethereum – Ethereum mainnet
sepolia – Ethereum Sepolia testnet

Solana Networks:

solana – Solana mainnet (high throughput, low fees)
solana-devnet – Solana devnet

Key Differences:

EVM: EIP-712 signatures, ERC-20 tokens (USDC), 0x-prefixed addresses
Solana: Ed25519 signatures, SPL tokens (USDC), Base58 addresses
Transaction finality: Solana (~400ms) vs EVM (12s-12min)
Gas costs: Solana (~$0.0001) vs EVM ($0.01-$10)

Code Structure Principles

1. Single Source of Truth

One type definition per concept. Avoid duplicate types. Use type composition or generics, not separate type definitions.

2. Encapsulation at the Right Level

Domain complexity belongs in the owning package. The payments package should handle all payments-related complexity.

3. Direct Exposure

Expose runtimes directly without unnecessary wrappers. If the type matches what’s needed, pass it through.

4. Consistency

Similar concepts should follow the same pattern. Consistency reduces cognitive load.

5. Public API Clarity

If something needs to be used by consumers, include it in the public type. Don’t hide methods or use type casts.

6. Simplicity Over Indirection

Avoid unnecessary getters, wrappers, and intermediate objects. Prefer straightforward code.

7. Domain Ownership

Each package should own its complexity and return what consumers need.

8. No Premature Abstraction

Keep it simple until you actually need the complexity. YAGNI (You Aren’t Gonna Need It) applies.

Monorepo Structure

/
âââ packages/
â   âââ core/               # Protocol-agnostic runtime
â   âââ http/               # HTTP extension
â   âââ wallet/             # Wallet SDK
â   âââ payments/           # x402 payment utilities
â   âââ analytics/          # Payment analytics
â   âââ identity/           # ERC-8004 identity
â   âââ a2a/                # A2A Protocol client
â   âââ ap2/                # AP2 extension
â   âââ hono/               # Hono adapter
â   âââ express/            # Express adapter
â   âââ tanstack/           # TanStack adapter
â   âââ cli/                # CLI scaffolding tool
âââ scripts/
âââ package.json            # Workspace config

Common Commands

Workspace-Level

# Install dependencies
bun install

# Build all packages
bun run build:packages

# Create changeset
bun run changeset

# Version packages
bun run release:version

# Publish packages
bun run release:publish

Package-Level

cd packages/[package-name]

# Build this package
bun run build

# Run tests
bun test

# Type check
bunx tsc --noEmit

API Quick Reference

Core Agent Creation

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

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,
};

Express Adapter

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

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

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

// Express apps need to listen on a port
const server = app.listen(process.env.PORT ?? 3000);

TanStack Adapter

import { createAgent } from '@lucid-agents/core';
import { http } from '@lucid-agents/http';
import { createTanStackRuntime } from '@lucid-agents/tanstack';

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

const { runtime: tanStackRuntime, handlers } = await createTanStackRuntime(agent);

// Use runtime.addEntrypoint() instead of addEntrypoint()
tanStackRuntime.addEntrypoint({ ... });

// Export for TanStack routes
export { runtime: tanStackRuntime, handlers };

Payments Extension

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();

Analytics Extension

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

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

// Get payment summary
const summary = await getSummary(agent.analytics.paymentTracker, 86400000);

// Export to CSV for accounting
const csv = await exportToCSV(agent.analytics.paymentTracker);

Identity Extension

import { createAgent } from '@lucid-agents/core';
import { wallets, walletsFromEnv } from '@lucid-agents/wallet';
import { identity, identityFromEnv } from '@lucid-agents/identity';

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

// Identity automatically handles ERC-8004 registration

A2A Extension

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

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

// Call another agent
const result = await agent.a2a.client.invoke(
  'https://other-agent.com',
  'skillId',
  { input: 'data' }
);

Streaming Entrypoints

addEntrypoint({
  key: 'chat',
  description: 'Chat with AI assistant',
  input: z.object({ message: z.string() }),
  streaming: true,
  async stream(ctx, emit) {
    const stream = await ai.chat.stream({ messages: [{ role: 'user', content: ctx.input.message }] });

    for await (const chunk of stream) {
      await emit({
        kind: 'delta',
        delta: chunk.delta,
        mime: 'text/plain',
      });
    }

    return {
      output: { completed: true },
      usage: { total_tokens: stream.usage.total_tokens },
    };
  },
});

CLI Usage

Interactive Mode

bunx @lucid-agents/cli my-agent

With Adapter Selection

# Hono adapter
bunx @lucid-agents/cli my-agent --adapter=hono

# Express adapter
bunx @lucid-agents/cli my-agent --adapter=express

# TanStack UI (full dashboard)
bunx @lucid-agents/cli my-agent --adapter=tanstack-ui

# TanStack Headless (API only)
bunx @lucid-agents/cli my-agent --adapter=tanstack-headless

Non-Interactive Mode

bunx @lucid-agents/cli my-agent \
  --adapter=hono \
  --template=axllm \
  --non-interactive \
  --AGENT_NAME="My AI Agent" \
  --AGENT_DESCRIPTION="AI-powered assistant" \
  --OPENAI_API_KEY=your_api_key_here \
  --PAYMENTS_RECEIVABLE_ADDRESS=0xYourAddress \
  --NETWORK=base-sepolia \
  --DEFAULT_PRICE=1000

Coding Standards

General

No emojis – Do not use emojis in code, comments, or commit messages unless explicitly requested
Re-exports are banned – Do not re-export types or values from other packages. Define types in @lucid-agents/types or in the package where they are used.

TypeScript

ESM only – Use import/export, not require()
Strict mode – All packages use strict: true
Explicit types – Avoid any, prefer explicit types or unknown
Type exports – Export types separately: export type { MyType }

File Naming

Source: kebab-case.ts
Types: types.ts or inline
Tests: *.test.ts in __tests__/
Examples: Descriptive names in examples/

Testing Local Packages

Use bun’s linking feature for testing local changes:

Register packages globally:

cd packages/types
bun link

cd ../wallet
bun link

Update test project’s package.json:

{
  "dependencies": {
    "@lucid-agents/wallet": "link:@lucid-agents/wallet"
  }
}

Install and test:
```
cd my-test-agent
bun install
```

Make changes and rebuild:

cd lucid-agents/packages/wallet
# Make changes
bun run build
# Changes reflected immediately

Common Development Tasks

Adding a New Feature to a Package

Create implementation in packages/[package]/src/feature.ts
Add types to types.ts or inline
Export from index.ts
Add tests in __tests__/feature.test.ts
Update package README.md and AGENTS.md
Create changeset: bun run changeset

Creating a New Template

Create directory: packages/cli/templates/my-template/
Add required files: src/agent.ts, src/index.ts, package.json, tsconfig.json
Create template.json with wizard configuration
Create template.schema.json documenting all arguments
Create AGENTS.md with comprehensive examples
Test: bunx ./packages/cli/dist/index.js test-agent --template=my-template

Troubleshooting

“Module not found” errors

Build all packages: bun run build:packages
Install dependencies: bun install
Check import paths are correct

TypeScript errors in templates

Build packages first
Check template package.json references correct versions
Run bunx tsc --noEmit in template directory

Build fails

Check TypeScript version matches across packages
Verify all imports are resolvable
Check for circular dependencies
Run bun install again

Key Files

packages/core/src/core/ – AgentCore, entrypoint management
packages/core/src/extensions/ – AgentBuilder, extension system
packages/http/src/extension.ts – HTTP extension definition
packages/payments/src/extension.ts – Payments extension
packages/identity/src/extension.ts – Identity extension
packages/hono/src/app.ts – Hono adapter implementation
packages/express/src/app.ts – Express adapter implementation
packages/tanstack/src/runtime.ts – TanStack adapter implementation
packages/cli/src/index.ts – CLI implementation

Resources

AGENTS.md – Full AI coding guide
CONTRIBUTING.md – Contribution guidelines
ERC-8004 Specification
x402 Protocol
A2A Protocol

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台