@elizaos/plugin-agent0

Agent0 SDK integration for elizaOS - provides agent registration, discovery, feedback, and reputation on the Agent0 network (ERC-8004 based).

Features

• Agent Registration: Register agents on the Agent0 network with IPFS metadata, MCP/A2A endpoints, and OASF taxonomies

  • Why: Makes your agent discoverable across the decentralized Agent0 network
  • Why IPFS: Decentralized, content-addressed storage ensures integrity and censorship resistance

• Agent Discovery: Search and discover agents by capabilities, tools, skills, reputation, and more

  • Why: Find the right agent for your task from thousands on the network
  • Why subgraph: Fast, indexed queries beat direct contract reads by 100x

• Feedback System: Give detailed feedback and ratings to agents with rich context

  • Why rich context: On-chain score + off-chain details (capability, task, proof) = actionable reputation
  • Why IPFS for context: Unlimited detail without gas costs

• Reputation Tracking: Query agent reputation from the Agent0 subgraph

  • Why: Due diligence before trusting an agent with important tasks
  • Why subgraph over contract: Pre-aggregated scores, fast queries, no RPC costs

• OASF Support: Manage Open Agentic Schema Framework skills and domains

  • Why: Standardized taxonomy enables semantic discovery ("find ML agents" not "find specific tools")
  • Why separate from MCP/A2A: OASF is domain-level, MCP/A2A are protocol-level

• Optional plugin-8004 Integration: Seamlessly coexists with plugin-8004 using validate()-based detection

  • Why coexist: plugin-8004 = contract-level operations, plugin-agent0 = discovery network
  • Why validate() detection: Avoids race conditions from parallel plugin loading

Installation

Dependencies

bun install

Note: There is currently a zod dependency loop issue in the monorepo that blocks installation. This is a pre-existing monorepo issue affecting multiple packages, not specific to plugin-agent0. The plugin implementation is complete and correct.

To use this plugin once the zod issue is resolved:

1. Ensure agent0-sdk is installed (specified in package.json)
2. Add plugin-agent0 to your elizaOS agent configuration

Configuration

Add these environment variables to your .env file:

Required

AGENT0_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY  # Ethereum RPC endpoint

Optional

# Wallet (required for write operations: register, feedback, OASF management)
AGENT0_PRIVATE_KEY=0x...                             # Agent0-specific private key
ERC8004_PRIVATE_KEY=0x...                            # Fallback (plugin-8004 compatibility)
EVM_PRIVATE_KEY=0x...                                # Fallback (shared wallet)

# Network
AGENT0_CHAIN_ID=11155111                             # Default: Sepolia (11155111)

# IPFS Configuration
AGENT0_IPFS_PROVIDER=pinata                          # Options: pinata, filecoinPin, node, none
AGENT0_PINATA_JWT=...                                # Required if provider=pinata
AGENT0_FILECOIN_PRIVATE_KEY=...                      # Required if provider=filecoinPin
AGENT0_IPFS_NODE_URL=http://localhost:5001          # Required if provider=node

Usage

In Your elizaOS Project

import { agent0Plugin } from '@elizaos/plugin-agent0';

const character = {
  // ... your character config
  plugins: [agent0Plugin],
};

With plugin-8004

plugin-agent0 detects plugin-8004 at runtime and defers registration and feedback actions to it when present. This allows using both plugins together:

• With plugin-8004: Agent0 adds discovery, search, reputation queries, and OASF management

  • Why defer registration: Both plugins write to same ERC-8004 contract, would duplicate
  • Why keep discovery: Agent0's subgraph provides capabilities plugin-8004 lacks
  • Result: Best of both worlds - contract-level control + network-level discovery

• Without plugin-8004: Agent0 provides full functionality including registration and feedback

  • Why self-contained: Simpler deployment, single plugin for everything
  • When to use: You only need Agent0 network features, not raw ERC-8004 contract access

ERC-8004 and other ecosystems

The Agent0 network uses the official ERC-8004 contract interface (split IdentityRegistry + ReputationRegistry, register(agentURI), tokenURI, giveFeedback, getSummary). Some ecosystems use Agent0 for discovery and reputation on the network while also running their own chain-specific contracts (different ABI) for game or app features. In those cases, this plugin covers the Agent0/official side; use the ecosystem’s plugin for that chain’s identity and reputation. For one example, see the Identity and reputation: Agent0 vs Babylon contracts section and the Identity and Reputation doc in @elizaos/plugin-babylon (docs/IDENTITY_AND_REPUTATION.md in that package).

Actions

REGISTER_AGENT0

Register an agent on the Agent0 network with IPFS, endpoints, and OASF taxonomies.

Trigger: "register on agent0", "publish agent", "make discoverable"

Requires: Private key (write operation)

Dormant when: plugin-8004 is present

Example:

User: Register me as TradingBot with MCP at https://mcp.example.com
Agent: ✅ Agent registered on Agent0 network! 🆔 Agent ID: 11155111:42

SEARCH_AGENT0

Search for agents by capabilities, tools, skills, reputation, etc.

Trigger: "search agents", "find agents", "agents with"

Read-only: Works without private key

Example:

User: Find agents with code generation tools
Agent: 🔍 Found 5 agents with code generation...

DISCOVER_AGENT0

Get detailed information about a specific agent.

Trigger: "agent details", "lookup agent", "what does agent X do"

Read-only: Works without private key

Example:

User: Show me details for agent 123
Agent: 📋 Agent Details: CodeBot - AI code generation assistant...

FEEDBACK_AGENT0

Give feedback/rating to an agent with rich context.

Trigger: "give feedback", "rate agent", "review agent"

Requires: Private key (write operation)

Dormant when: plugin-8004 is present

Example:

User: Give agent 42 a score of 90 for their trading advice
Agent: ✅ Feedback submitted! Score: 90/100

REPUTATION_AGENT0

Get reputation summary from the Agent0 subgraph.

Trigger: "reputation", "how trusted", "agent rating"

Read-only: Works without private key

Always active: Provides subgraph-powered search that plugin-8004 lacks

Example:

User: What's the reputation of agent 123?
Agent: ⭐ Average Score: 87.5/100, Total Feedback: 24

MANAGE_OASF

Manage OASF skills and domains for an agent.

Trigger: "add skill", "add domain", "OASF", "set capabilities"

Requires: Private key (write operation) and agent must be registered

Example:

User: Add skill data_engineering/data_transformation_pipeline to agent 123
Agent: ✅ OASF skill added and metadata updated!

Architecture

Service: Agent0Service

Wraps the Agent0 SDK (agent0-sdk) with lazy initialization and elizaOS integration.

Why wrap the SDK instead of using directly in actions?

• Centralized configuration and error handling
• Lazy initialization (don't connect until needed)
• Shared SDK instance across all actions (efficiency)
• Runtime integration (logger, cache, config)
• Easy to mock for testing
• Follows elizaOS service pattern

Why lazy initialization (getSDK() not constructor)?

• Service is registered even if config is incomplete (graceful degradation)
• Some actions are read-only and might work with partial config
• Avoids failing the entire plugin if Agent0 is misconfigured
• User sees helpful error at action time, not cryptic startup failure

Key Methods:

• getSDK() - Get initialized SDK instance (lazy, cached)
• createAgent() / loadAgent() - Agent management
• registerAgent() - Register with IPFS or HTTP (prefers IPFS for decentralization)
• searchAgents() / getAgent() - Discovery via subgraph
• giveFeedback() / getReputationSummary() - Reputation management
• canWrite() - Check wallet availability (enables/disables write actions)

Providers

• agent0DiscoveryProvider: Reports Agent0 network status and capabilities
• agent0ReputationProvider: Provides reputation system context

plugin-8004 Detection

The plugin uses validate()-based detection at message time (not init time) to avoid race conditions:

validate: async (runtime: IAgentRuntime, message: Memory): Promise<boolean> => {
    // If plugin-8004 is loaded, defer to it
    if (runtime.getService('ERC8004_IDENTITY')) return false;
    // ... normal validation
}

Why detection in validate() instead of init()?

❌ What doesn't work: Checking runtime.getService() in init()

• Plugins load in parallel via Promise.all (runtime.ts:396-401)
• Services register asynchronously after plugin init
• Race condition: plugin-8004 might not be available yet
• Would give inconsistent results depending on plugin load order

✅ What works: Checking runtime.getService() in validate()

• By message time, all plugins are fully loaded and initialized
• Services are guaranteed to be registered
• Reliable detection every time
• Standard elizaOS pattern (see plugin-babylon)

Why static registration + validate filtering (not dynamic registration)?

• All 6 actions are registered at plugin init
• Overlapping actions return false from validate() when plugin-8004 detected
• Action exists but is invisible to LLM (filtered out of context)
• Simpler code than conditional array building
• Easier to debug (action is always there, just filtered)

Development

Build

bun run build

Lint/Format

bun run lint
bun run format

Implementation Notes

Critical Details

• npm package: agent0-sdk (NOT @agent0/sdk - the landing page is incorrect)

  • Why important: Installing wrong package = runtime errors
  • Where confusion comes from: Agent0's landing page shows @agent0/sdk but that package doesn't exist

• ESM only: Plugin uses "type": "module"

  • Why: agent0-sdk is ESM-only, can't use CommonJS
  • Compatibility: Matches elizaOS's ESM migration

• Private key format: Viem expects 0x prefix - automatically normalized

  • Why matters: agent0-sdk uses viem (requires 0x), plugin-8004 uses ethers (accepts both)
  • Solution: We auto-add 0x if missing, safe for both libraries

• IPFS: Fully configurable via environment, defaults to Pinata

  • Why not plugin-ipfs: Agent0 SDK has its own IPFS handling
  • Why Pinata default: Most reliable, no infrastructure needed

Performance & UX

• Transaction timeouts: 180s for registration and feedback

  • Why so long: IPFS upload (5-30s) + block confirmation (12-60s) + congestion buffer
  • Why timeout at all: Don't hang forever if network is down

• Search result limits: Capped at 20 to avoid overwhelming chat

  • Why limit: Agent0 SDK removed pagination, returns ALL results
  • Why 20: Sweet spot between useful and readable in chat UI

• Cache TTLs: Discovery status and reputation cached for 5 minutes

  • Why cache: Subgraph queries have latency, avoid repeated calls
  • Why 5min: Balance between freshness and efficiency

Troubleshooting

"Agent0Service not available"

Symptom: Actions fail with "Agent0Service not available" error

Causes & Solutions:

1. Missing AGENT0_RPC_URL in .env

   • Why critical: SDK can't connect to Ethereum without RPC endpoint
   • Fix: Add AGENT0_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY to .env

2. Plugin not loaded in character config

   • Why happens: Forgot to add to plugins: [] array
   • Fix: Add import { agent0Plugin } from '@elizaos/plugin-agent0' and include in plugins array

3. Service failed to initialize (check logs)

   • Why happens: Invalid RPC URL or network issues
   • Fix: Check console for detailed error messages from Agent0Service.start()

"No wallet configured"

Symptom: Write operations (register, feedback, OASF) fail

Why: These operations require signing transactions on-chain

Solutions:

1. Set one of: AGENT0_PRIVATE_KEY, ERC8004_PRIVATE_KEY, or EVM_PRIVATE_KEY
2. Use 0x prefix for compatibility (we auto-add if missing)
3. Note: Read operations (search, discover, reputation) work WITHOUT a wallet

Security: Never commit private keys to git. Use .env file (gitignored).

"Package 'zod' has a dependency loop"

Symptom: bun install fails with DependencyLoop error

Why: Monorepo has mixed zod v3 (plugins) and v4 (core) versions, Bun can't resolve

Scope: Pre-existing monorepo issue affecting many packages, NOT specific to plugin-agent0

Status: Plugin implementation is complete and correct, just blocked on monorepo dependency resolution

Workarounds attempted (none worked):

• ❌ bun install --force - Still fails
• ❌ npm install --legacy-peer-deps - Doesn't support workspace: protocol
• ❌ Resolutions/overrides - Ignored by transitive deps

Resolution needed: Update all monorepo packages to use consistent zod version

Related 8004 elizaOS plugins

• plugin-8004 - Official ERC-8004 identity and reputation (multi-chain)
• plugin-babylon - Babylon prediction markets, perpetuals, social, and identity

License

MIT

Links

• Agent0 Docs
• Agent0 GitHub
• elizaOS