Architecture

Agent0 SDK provides a unified interface for managing agent identities, enabling discovery, and building reputation on blockchain infrastructure.

High-Level Architecture

What Stays Where

Blockchain (On-chain)

• Agent identities (ERC-721 NFTs)
• Basic metadata (wallet address, ENS name)
• Feedback scores and tags
• Cryptographic commitments to off-chain files
• Ownership and operator permissions

Decentralized Storage (Off-chain)

• Complete agent registration files (IPFS/HTTP)
• Detailed feedback data (context, capability info, payment proofs)
• Agent images and additional metadata

Developer Applications

• SDK instance with configuration
• Agent management and registration
• Search and discovery operations
• Feedback submission and retrieval

End Users

• Discover agents through search
• Interact with agents via endpoints
• Give feedback and build reputation
• Access agent capabilities

Core Flows

1. Agent Registration Flow

Step-by-step process:

1. Create Agent → Developer calls SDK.createAgent()

   • Creates in-memory RegistrationFile object
   • No blockchain interaction yet

2. Configure Agent → Developer calls agent.setMCP(), agent.setA2A(), etc.

   • SDK automatically fetches capabilities from endpoints (tools, prompts, resources, skills)
   • Updates RegistrationFile locally with fetched capabilities
   • Soft fails if MCP/A2A endpoints are unreachable (non-blocking)

3. Mint Agent Identity → SDK calls IdentityRegistry.register()

   • Mints ERC-721 NFT representing agent
   • Returns unique agentId

4. Update Registration File → SDK adds agentId to RegistrationFile

   • Inserts the minted agentId into the registration data
   • Updates the registrations array with agent ID and registry address

5. Upload Registration File → Developer calls agent.registerIPFS()

   • Uploads complete RegistrationFile (with agentId) to IPFS → Gets CID
   • Alternative: agent.registerHTTP() for HTTP storage

6. Link File to Identity → SDK calls IdentityRegistry.setAgentUri(CID)

   • Stores IPFS CID on-chain
   • Creates tamper-proof link between identity and file

7. Index Agent → Subgraph automatically indexes

   • Subgraph monitors blockchain events and IPFS updates
   • Extracts capabilities from registration files
   • Makes agent discoverable via GraphQL queries

2. Agent Discovery Flow

Search process:

1. Query Preparation → Developer calls SDK.searchAgents(params)

   • Builds search parameters (name, capabilities, trust models, etc.)

2. Search Execution → SDK queries subgraph

   • Fast GraphQL queries for complex filtering
   • Real-time results from indexed data

3. Result Processing → SDK returns AgentSummary objects

   • Includes basic info, capabilities, reputation
   • Links to full registration files

4. Detailed Retrieval → Developer calls SDK.getAgent(agentId)

   • Queries subgraph for agent data and registration file
   • Returns AgentSummary with full agent configuration

3. Feedback Submission Flow

Two storage options:

Option A: On-chain Only (Simple)

1. Prepare Feedback → Developer calls SDK.prepareFeedback()

   • Creates feedback with score and tags only
   • No off-chain file needed

2. Submit to Blockchain → SDK calls ReputationRegistry.giveFeedback()

   • Stores score and tags directly on-chain
   • Minimal gas costs

Option B: Hybrid (Recommended)

1. Create Feedback File → Developer calls SDK.prepareFeedback()

   • Creates detailed feedback file with context, capability info, payment proofs

2. Upload to Storage → SDK uploads to IPFS/HTTP

   • Gets CID or URI for feedback file
   • Stores complete feedback data

3. Submit Commitment → SDK calls ReputationRegistry.giveFeedback()

   • Stores score, tags, and file commitment on-chain
   • Creates tamper-proof link to detailed feedback

4. Index Feedback → Subgraph automatically indexes

   • Monitors blockchain events (NewFeedback) and IPFS updates
   • Makes feedback searchable and discoverable

4. Agent Update Flow

Modifying existing agents:

1. Load Agent → Developer calls SDK.loadAgent(agentId)

   • Retrieves current RegistrationFile from IPFS/HTTP
   • Loads into Agent object for updates

2. Modify Configuration → Developer calls update methods

   • agent.setMCP(), agent.setA2A(), etc.
   • Updates RegistrationFile locally

3. Upload New File → Developer calls agent.registerIPFS()

   • Uploads updated RegistrationFile to IPFS
   • Gets new CID

4. Update On-chain Reference → SDK calls IdentityRegistry.setAgentUri(newCID)

   • Updates IPFS CID on-chain
   • Maintains link to latest version

5. Re-index Agent → Subgraph automatically re-indexes

   • Monitors blockchain events (UriUpdated) and IPFS updates
   • Reflects new capabilities and configuration

5. Agent Transfer Flow

Changing ownership:

1. Load Agent → Developer calls SDK.loadAgent(agentId)

   • Retrieves current agent configuration

2. Transfer Ownership → Developer calls SDK.transferAgent(agentId, newOwner)

   • SDK loads agent and calls IdentityRegistry.transferFrom()
   • Transfers ERC-721 NFT to new owner

6. Feedback Retrieval Flow

Getting feedback data:

1. Get Feedback → Developer calls SDK.getFeedback(feedbackId)

   • SDK queries ReputationRegistry for feedback records
   • Gets on-chain scores, tags, and file commitments

2. Retrieve Details → SDK fetches feedback files from IPFS/HTTP

   • Downloads complete feedback data
   • Parses context, capability info, payment proofs

3. Return Results → SDK returns Feedback object

   • Combines on-chain and off-chain data
   • Provides complete feedback information