Lucid Agents Docs

The identity examples demonstrate how to register agents on the ERC-8004 registry and interact with identity, reputation, and validation registries.

Quick Start

File: packages/examples/src/identity/quick-start.ts

The simplest way to register your agent on-chain.

The code

quick-start.ts

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

async function main() {
  // Create a minimal runtime with wallet configuration
  const agent = await createAgent({
    name: 'quick-start-agent',
    version: '1.0.0',
    description: 'Quick start example agent',
  })
    .use(wallets({ config: walletsFromEnv() }))
    .build();

  // Example 1: Simple registration with env vars
  console.log('Example 1: Simple Registration');
  const identity = await createAgentIdentity({
    runtime: agent,
    autoRegister: true,
  });

  console.log('Status:', identity.status);

  if (identity.didRegister) {
    console.log('Agent registered successfully!');
    console.log('Transaction:', identity.transactionHash);
    console.log(
      'Next step: Host your registration file at:',
      `https://${identity.domain}/.well-known/agent-registration.json`
    );
  } else if (identity.trust) {
    console.log('Found existing registration');
    console.log('Agent ID:', identity.record?.agentId);
  } else {
    console.log('No on-chain identity (agent will run without it)');
  }

  // Example 2: Explicit registration
  console.log('Example 2: Explicit Registration');
  const registration = await registerAgent({
    runtime: agent,
    domain: 'my-agent.example.com',
  });

  console.log('Status:', registration.status);
  if (registration.didRegister) {
    console.log('TX:', registration.transactionHash);
  }

  // Example 3: Custom configuration
  console.log('Example 3: Custom Configuration');
  const customIdentity = await createAgentIdentity({
    runtime: agent,
    domain: 'custom-agent.example.com',
    autoRegister: true,
    trustModels: ['feedback', 'tee-attestation'],
    trustOverrides: {
      feedbackDataUri: 'https://custom-agent.example.com/feedback.json',
    },
  });

  console.log('Status:', customIdentity.status);
  if (customIdentity.trust) {
    console.log('Trust models:', customIdentity.trust.trustModels);
    console.log('Feedback URI:', customIdentity.trust.feedbackDataUri);
  }
}

main().catch(console.error);

Key patterns explained

Auto-registration

The simplest path - set autoRegister: true and the SDK handles everything:

const identity = await createAgentIdentity({
  runtime: agent,
  autoRegister: true,  // Register if not already registered
});

Explicit registration

When you want more control over when registration happens:

const registration = await registerAgent({
  runtime: agent,
  domain: 'my-agent.example.com',
});

Custom trust models

Configure which trust models your agent supports:

const identity = await createAgentIdentity({
  runtime: agent,
  domain: 'custom-agent.example.com',
  autoRegister: true,
  trustModels: ['feedback', 'tee-attestation'],
  trustOverrides: {
    feedbackDataUri: 'https://custom-agent.example.com/feedback.json',
  },
});

Available trust models:

feedback - Reputation feedback system
tee-attestation - Trusted Execution Environment attestation
domain - Domain ownership verification

Environment variables

# Required
AGENT_WALLET_PRIVATE_KEY=0x...
RPC_URL=https://sepolia.base.org
CHAIN_ID=84532

# Optional
AGENT_DOMAIN=my-agent.example.com

Running the example

bun run packages/examples/src/identity/quick-start.ts

Full Integration

File: packages/examples/src/identity/full-integration.ts

Comprehensive example testing all three registries: Identity, Validation, and Reputation.

What it demonstrates

Identity Registry
- Registration and lookups
- Metadata management
- Multiple agents per wallet
Validation Registry
- Creating validation requests
- Submitting validation responses
- Querying validation status
Reputation Registry
- Giving feedback to agents
- Responding to feedback
- Querying reputation summaries

Key operations

// Identity Registry
const record = await registry.identity.get(agentId);
const metadata = await registry.identity.getMetadata(agentId, 'version');
await registry.identity.setMetadata(
  agentId,
  'version',
  new TextEncoder().encode('1.0.0')
);

// Validation Registry
// hashValidationRequest is exported from @lucid-agents/identity
const requestBody = '{"input":"work-data"}';
const requestHash = hashValidationRequest(requestBody);
await registry.validation.validationRequest({
  validatorAddress,
  agentId,
  requestUri: 'ipfs://...',
  requestBody,
});
await registry.validation.validationResponse({
  requestHash,
  response: 1,
  responseUri: 'ipfs://...',
  responseHash,
  tag: 'validation',
});

// Reputation Registry
const reputation = await registry.reputation.getSummary(agentId);
const average =
  reputation.valueDecimals === 0
    ? Number(reputation.value)
    : Number(reputation.value) / 10 ** reputation.valueDecimals;
await registry.reputation.giveFeedback({
  toAgentId: agentId,
  value: 5,
  valueDecimals: 0,
  tag1: 'quality',
  tag2: 'speed',
});
await registry.reputation.appendResponse(feedbackId, { ... });

Test Clients

File: packages/examples/src/identity/test-clients.ts

A quick validation that all registry clients are properly initialized.

import { createAgentIdentity } from '@lucid-agents/identity';

const identity = await createAgentIdentity({ runtime: agent });

// Access individual clients
console.log('Identity client:', identity.clients.identity.address);
console.log('Reputation client:', identity.clients.reputation.address);
console.log('Validation client:', identity.clients.validation.address);

// Check chain configuration
console.log('Chain ID:', identity.clients.identity.chainId);

Why this matters

The test clients example verifies:

Registry contract addresses are correctly configured
RPC connection is working
Client methods are available

This is useful for debugging configuration issues before running full integration tests.

Identity Examples