diff --git a/.gitignore b/.gitignore index 2ffd990b4054..59f1204d6ed1 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,4 @@ dist/ .turbo/ packages/og-image/vendor/*.wasm .wrangler/ +.Rproj.user diff --git a/website/src/pages/en/subgraphs/guides/_meta.js b/website/src/pages/en/subgraphs/guides/_meta.js index 07c6de9c95bc..f187cf82b68f 100644 --- a/website/src/pages/en/subgraphs/guides/_meta.js +++ b/website/src/pages/en/subgraphs/guides/_meta.js @@ -9,5 +9,6 @@ export default { enums: '', 'secure-api-keys-nextjs': '', polymarket: '', + agent0: '', 'contract-analyzer': '', } diff --git a/website/src/pages/en/subgraphs/guides/agent0.mdx b/website/src/pages/en/subgraphs/guides/agent0.mdx new file mode 100644 index 000000000000..566e375d5e81 --- /dev/null +++ b/website/src/pages/en/subgraphs/guides/agent0.mdx @@ -0,0 +1,230 @@ +--- +title: Agent0 Subgraphs (ERC-8004) +sidebarTitle: Agent0 Subgraphs +--- + +The **Agent0 Subgraphs** index the [ERC-8004 Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004) 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](https://sdk.ag0.xyz/docs) 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](https://github.com/agent0lab/subgraph). + +## Supported networks + +| Network | Chain ID | Status | Endpoint | Explorer | +| --- | --- | --- | --- | --- | +| **Ethereum Mainnet** | 1 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/FV6RR6y13rsnCxBAicKuQEwDp8ioEGiNaWaZUmvr1F8k) | [Explorer](https://thegraph.com/explorer/subgraphs/FV6RR6y13rsnCxBAicKuQEwDp8ioEGiNaWaZUmvr1F8k?view=Query&chain=arbitrum-one) | +| **Base Mainnet** | 8453 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/43s9hQRurMGjuYnC1r2ZwS6xSQktbFyXMPMqGKUFJojb) | [Explorer](https://thegraph.com/explorer/subgraphs/43s9hQRurMGjuYnC1r2ZwS6xSQktbFyXMPMqGKUFJojb?view=Query&chain=arbitrum-one) | +| **BSC Mainnet** | 56 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/D6aWqowLkWqBgcqmpNKXuNikPkob24ADXCciiP8Hvn1K) | [Explorer](https://thegraph.com/explorer/subgraphs/D6aWqowLkWqBgcqmpNKXuNikPkob24ADXCciiP8Hvn1K?view=Query&chain=arbitrum-one) | +| **Polygon Mainnet** | 137 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/9q16PZv1JudvtnCAf44cBoxg82yK9SSsFvrjCY9xnneF) | [Explorer](https://thegraph.com/explorer/subgraphs/9q16PZv1JudvtnCAf44cBoxg82yK9SSsFvrjCY9xnneF?view=Query&chain=arbitrum-one) | +| **Monad** | 143 | ✅ Deployed | [Endpoint](https://thegraph.com/explorer/subgraphs/4tvLxkczjhSaMiqRrCV1EyheYHyJ7Ad8jub1UUyukBjg?view=Query&chain=arbitrum-one) | [Explorer](https://thegraph.com/explorer/subgraphs/4tvLxkczjhSaMiqRrCV1EyheYHyJ7Ad8jub1UUyukBjg?view=Query&chain=arbitrum-one) | +| **Ethereum Sepolia** | 11155111 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/6wQRC7geo9XYAhckfmfo8kbMRLeWU8KQd3XsJqFKmZLT) | [Explorer](https://thegraph.com/explorer/subgraphs/6wQRC7geo9XYAhckfmfo8kbMRLeWU8KQd3XsJqFKmZLT?view=Query&chain=arbitrum-one) | +| **Base Sepolia** | 84532 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/4yYAvQLFjBhBtdRCY7eUWo181VNoTSLLFd5M7FXQAi6u) | [Explorer](https://thegraph.com/explorer/subgraphs/4yYAvQLFjBhBtdRCY7eUWo181VNoTSLLFd5M7FXQAi6u?view=Query&chain=arbitrum-one) | +| **BSC Chapel** | 97 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/BTjind17gmRZ6YhT9peaCM13SvWuqztsmqyfjpntbg3Z) | [Explorer](https://thegraph.com/explorer/subgraphs/BTjind17gmRZ6YhT9peaCM13SvWuqztsmqyfjpntbg3Z?view=Query&chain=arbitrum-one) | +| **Monad Testnet** | 10143 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/8iiMH9sj471jbp7AwUuuyBXvPJqCEsobuHBeUEKQSxhU) | [Explorer](https://thegraph.com/explorer/subgraphs/8iiMH9sj471jbp7AwUuuyBXvPJqCEsobuHBeUEKQSxhU?view=Query&chain=arbitrum-one) | +| **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](https://thegraph.com/studio) and generate an API key. + +### 2. Find your endpoint + +Search **agent0** on [Graph Explorer](https://thegraph.com/explorer?search=agent0) and copy the Subgraph ID for the network you want. Endpoints follow this pattern: + +``` +https://gateway.thegraph.com/api//subgraphs/id/ +``` + +### 3. Run a query + +#### cURL + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{"query": "{ agents(first: 5) { id registrationFile { name description mcpEndpoint } } }"}' \ + https://gateway.thegraph.com/api//subgraphs/id/ +``` + +#### TypeScript + +```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 + +```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](https://sdk.ag0.xyz/docs)? 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 + +```graphql +query GetMCPAgents { + agentRegistrationFiles(where: { mcpEndpoint_not: null, active: true }, first: 100) { + agentId + name + description + mcpEndpoint + mcpVersion + mcpTools + supportedTrusts + } +} +``` + +### Get a complete agent profile + +```graphql +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 + +```graphql +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 + +```graphql +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`](https://github.com/agent0lab/subgraph/blob/main/schema.graphql). + +## Resources + +- **Agent0 SDK:** TypeScript and Python SDK for ERC-8004 registration, discovery, and reputation: [sdk.ag0.xyz/docs](https://sdk.ag0.xyz/docs) +- **Subgraph repo:** Open-source mappings, schema, and multi-chain deployment config: [github.com/agent0lab/subgraph](https://github.com/agent0lab/subgraph) +- **ERC-8004 spec:** The Trustless Agents standard: [eips.ethereum.org/EIPS/eip-8004](https://eips.ethereum.org/EIPS/eip-8004) +- **Graph Explorer:** Browse all Agent0 Subgraphs: [thegraph.com/explorer?search=agent0](https://thegraph.com/explorer?search=agent0)