Skip to content

agent0.mdx

Latest commit

 

History

History
230 lines (187 loc) · 9.72 KB

agent0.mdx

File metadata and controls

230 lines (187 loc) · 9.72 KB
title Agent0 Subgraphs (ERC-8004)
sidebarTitle Agent0 Subgraphs

The Agent0 Subgraphs index the ERC-8004 Trustless Agents registries — Identity, Reputation, and Validation — across five major networks. They give developers a single GraphQL interface to discover agents, filter by capability, query reputation, and track validation outcomes in real time.

Built and maintained by Agent0 in partnership with The Graph.

Note: Agent0 Subgraphs are a public good. The schema, mappings, and deployment configs are open-source and available at github.com/agent0lab/subgraph.

Supported networks

Network Chain ID Status Endpoint Explorer
Ethereum Mainnet 1 ✅ Deployed Endpoint Explorer
Base Mainnet 8453 ✅ Deployed Endpoint Explorer
BSC Mainnet 56 ✅ Deployed Endpoint Explorer
Polygon Mainnet 137 ✅ Deployed Endpoint Explorer
Monad 143 ✅ Deployed Endpoint Explorer
Ethereum Sepolia 11155111 ✅ Deployed Endpoint Explorer
Base Sepolia 84532 ✅ Deployed Endpoint Explorer
BSC Chapel 97 ✅ Deployed Endpoint Explorer
Monad Testnet 10143 ✅ Deployed Endpoint Explorer
Polygon Amoy 80002 ⛔️ Subgraphs not deployed - -
Linea Sepolia 59141 ⛔️ Subgraphs not deployed - -
Hedera Testnet 296 ⛔️ Subgraphs not deployed - -
HyperEVM Testnet 998 ⛔️ Subgraphs not deployed - -
SKALE Base Sepolia 1351057110 ⛔️ Subgraphs not deployed - -

A single GraphQL schema is shared across all available deployments, so the same query works on every chain — only the endpoint URL changes.

What's indexed

Domain Data
Agent registrations Identity (ERC-721 token), owner, operators, registration URI, ENS, DID, agent wallet, x402 support, supported trust models, name, description, image
Capabilities MCP endpoint, version, tools, prompts, resources. A2A endpoint, version, skills. OASF taxonomy tags
Feedback Score (0–100), tags, client address, off-chain feedback file (text, capability, skill, task, proof of payment), revocation status, responses
Validation Validator address, request/response URIs, score, tag, status (pending, completed, expired)
Aggregates Per-agent stats (avg score, score distribution, totals), per-chain protocol entity, global cross-chain rollup

Off-chain registration and feedback files (IPFS or HTTPS) are fetched and parsed via File Data Sources, so JSON metadata is queryable alongside on-chain events — no separate IPFS round trip required from the client.

Why use the Subgraph

  • Fast search: Query thousands of agents in milliseconds. Filter by capability, score, trust model, or chain.
  • Rich filtering: Combine on-chain and off-chain fields in a single GraphQL query.
  • Real-time data: New registrations, feedback, and validation events are indexed automatically as they're emitted.
  • No RPC limits: Skip rate-limited RPC scans and IPFS round-trips. One query, one response.

Quick start

1. Get an API key

Create a free account on Subgraph Studio and generate an API key.

2. Find your endpoint

Search agent0 on Graph Explorer and copy the Subgraph ID for the network you want. Endpoints follow this pattern:

https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>

3. Run a query

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "{ agents(first: 5) { id registrationFile { name description mcpEndpoint } } }"}' \
  https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>

TypeScript

const res = await fetch(`https://gateway.thegraph.com/api/${API_KEY}/subgraphs/id/${SUBGRAPH_ID}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `{
        agents(first: 5) {
          id
          registrationFile { name description mcpEndpoint }
        }
      }`,
  }),
})
const { data } = await res.json()

Python

import requests

url = f"https://gateway.thegraph.com/api/{API_KEY}/subgraphs/id/{SUBGRAPH_ID}"
query = """{
  agents(first: 5) {
    id
    registrationFile { name description mcpEndpoint }
  }
}"""
res = requests.post(url, json={"query": query}).json()

Tip: Using the Agent0 SDK? Subgraph endpoints are wired up by default — you can call sdk.searchAgents(...) and sdk.searchFeedback(...) without writing GraphQL by hand.

Common queries

Find MCP-compatible agents

query GetMCPAgents {
  agentRegistrationFiles(where: { mcpEndpoint_not: null, active: true }, first: 100) {
    agentId
    name
    description
    mcpEndpoint
    mcpVersion
    mcpTools
    supportedTrusts
  }
}

Get a complete agent profile

query GetAgent {
  agent(id: $id) {
    # example: "8453:0"
    id
    chainId
    agentId
    owner
    createdAt
    totalFeedback
    registrationFile {
      name
      description
      image
      mcpEndpoint
      mcpTools
      a2aEndpoint
      a2aSkills
      supportedTrusts
      x402Support
      ens
      did
    }
    feedback(where: { isRevoked: false }, first: 10, orderBy: createdAt, orderDirection: desc) {
      tag1
      tag2
      clientAddress
      feedbackFile {
        text
      }
    }
    validations(orderBy: createdAt, orderDirection: desc) {
      validatorAddress
      response
      status
      tag
    }
  }
}

The agent id is formatted as chainId:agentId (e.g. 8453:1247 for agent 1247 on Base).

Filter agents by trust model

query AgentsByTrust($trustModel: String!) {
  agentRegistrationFiles(where: { supportedTrusts_contains: [$trustModel], active: true }, first: 50) {
    agentId
    name
    description
    supportedTrusts
  }
}

Common values: "reputation", "cryptoeconomic", "tee-attestation".

Top-rated feedback across the network

query TopFeedback {
  feedbacks(where: { isRevoked: false, value_gte: 1000 }, first: 50, orderBy: value, orderDirection: desc) {
    value
    tag1
    tag2
    agent {
      id
      registrationFile {
        name
      }
    }
    feedbackFile {
      text
    }
  }
}

Schema reference

Core entities:

  • Agent: Onchain identity, mutable. Linked to AgentRegistrationFile, Feedback[], Validation[], AgentStats.
  • AgentRegistrationFile: Immutable, parsed from the IPFS/HTTPS registration URI. Contains all advertised capabilities.
  • Feedback: Onchain feedback entry. Linked to optional FeedbackFile for off-chain text and proof of payment.
  • FeedbackFile: Immutable, parsed from the feedback URI.
  • Validation: Validation request and response lifecycle. Status: PENDING, COMPLETED, EXPIRED.
  • protocolAgentStats: Per-agent rollup (total feedback, average score, score distribution).
  • Protocol: Per-chain rollup.

Full schema: schema.graphql.

Resources