Skip to content

Commit 5e7ced6

Browse files
brandonleekramerbrandonleekramer
committed
Added agent0.mdx
1 parent 9b5fd81 commit 5e7ced6

2 files changed

Lines changed: 235 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,4 @@ dist/
3939
.turbo/
4040
packages/og-image/vendor/*.wasm
4141
.wrangler/
42+
.Rproj.user

‎website/src/pages/en/subgraphs/guides/agent0.mdx‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Agent0 Subgraphs (ERC-8004)
2+
3+
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.
4+
5+
Built and maintained by [Agent0](https://sdk.ag0.xyz/docs) in partnership with The Graph.
6+
7+
> **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).
8+
9+
## Supported networks
10+
11+
| Network | Chain ID | Status | Endpoint | Explorer |
12+
|---------|----------|--------|----------|----------|
13+
| **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) |
14+
| **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) |
15+
| **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) |
16+
| **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) |
17+
| **Monad** | 143 | ✅ Deployed | [Endpoint](https://thegraph.com/explorer/subgraphs/4tvLxkczjhSaMiqRrCV1EyheYHyJ7Ad8jub1UUyukBjg?view=Query&chain=arbitrum-one) |
18+
| **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) |
19+
| **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) |
20+
| **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) |
21+
| **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) |
22+
| **Polygon Amoy** | 80002 | ⛔️ Subgraphs not deployed | - |
23+
| **Linea Sepolia** | 59141 | ⛔️ Subgraphs not deployed | - |
24+
| **Hedera Testnet** | 296 | ⛔️ Subgraphs not deployed | - |
25+
| **HyperEVM Testnet** | 998 | ⛔️ Subgraphs not deployed | - |
26+
| **SKALE Base Sepolia** | 1351057110 | ⛔️ Subgraphs not deployed | - |
27+
28+
A single GraphQL schema is shared across all available deployments, so the same query works on every chain — only the endpoint URL changes.
29+
30+
## What's indexed
31+
32+
| Domain | Data |
33+
| --- | --- |
34+
| **Agent registrations** | Identity (ERC-721 token), owner, operators, registration URI, ENS, DID, agent wallet, x402 support, supported trust models, name, description, image |
35+
| **Capabilities** | MCP endpoint, version, tools, prompts, resources. A2A endpoint, version, skills. OASF taxonomy tags |
36+
| **Feedback** | Score (0–100), tags, client address, off-chain feedback file (text, capability, skill, task, proof of payment), revocation status, responses |
37+
| **Validation** | Validator address, request/response URIs, score, tag, status (pending, completed, expired) |
38+
| **Aggregates** | Per-agent stats (avg score, score distribution, totals), per-chain protocol entity, global cross-chain rollup |
39+
40+
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.
41+
42+
## Why use the Subgraph
43+
44+
- **Fast search:** Query thousands of agents in milliseconds. Filter by capability, score, trust model, or chain.
45+
- **Rich filtering:** Combine on-chain and off-chain fields in a single GraphQL query.
46+
- **Real-time data:** New registrations, feedback, and validation events are indexed automatically as they're emitted.
47+
- **No RPC limits:** Skip rate-limited RPC scans and IPFS round-trips. One query, one response.
48+
49+
## Quick start
50+
51+
### 1. Get an API key
52+
53+
Create a free account on [Subgraph Studio](https://thegraph.com/studio) and generate an API key.
54+
55+
### 2. Find your endpoint
56+
57+
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:
58+
59+
```
60+
https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>
61+
```
62+
63+
### 3. Run a query
64+
65+
**cURL**
66+
67+
```bash
68+
curl -X POST \
69+
-H "Content-Type: application/json" \
70+
-d '{"query": "{ agents(first: 5) { id registrationFile { name description mcpEndpoint } } }"}' \
71+
https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>
72+
```
73+
74+
**TypeScript**
75+
76+
```typescript
77+
const res = await fetch(
78+
`https://gateway.thegraph.com/api/${API_KEY}/subgraphs/id/${SUBGRAPH_ID}`,
79+
{
80+
method: "POST",
81+
headers: { "Content-Type": "application/json" },
82+
body: JSON.stringify({
83+
query: `{
84+
agents(first: 5) {
85+
id
86+
registrationFile { name description mcpEndpoint }
87+
}
88+
}`,
89+
}),
90+
}
91+
);
92+
const { data } = await res.json();
93+
```
94+
95+
**Python**
96+
97+
```python
98+
import requests
99+
100+
url = f"https://gateway.thegraph.com/api/{API_KEY}/subgraphs/id/{SUBGRAPH_ID}"
101+
query = """{
102+
agents(first: 5) {
103+
id
104+
registrationFile { name description mcpEndpoint }
105+
}
106+
}"""
107+
res = requests.post(url, json={"query": query}).json()
108+
```
109+
110+
> **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.
111+
112+
## Common queries
113+
114+
### Find MCP-compatible agents
115+
116+
```graphql
117+
query GetMCPAgents {
118+
agentRegistrationFiles(
119+
where: { mcpEndpoint_not: null, active: true }
120+
first: 100
121+
) {
122+
agentId
123+
name
124+
description
125+
mcpEndpoint
126+
mcpVersion
127+
mcpTools
128+
supportedTrusts
129+
}
130+
}
131+
```
132+
133+
### Get a complete agent profile
134+
135+
```graphql
136+
query GetAgent {
137+
agent(id: $id) { # example: "8453:0"
138+
id
139+
chainId
140+
agentId
141+
owner
142+
createdAt
143+
totalFeedback
144+
registrationFile {
145+
name
146+
description
147+
image
148+
mcpEndpoint
149+
mcpTools
150+
a2aEndpoint
151+
a2aSkills
152+
supportedTrusts
153+
x402Support
154+
ens
155+
did
156+
}
157+
feedback(where: { isRevoked: false }, first: 10, orderBy: createdAt, orderDirection: desc) {
158+
tag1
159+
tag2
160+
clientAddress
161+
feedbackFile { text }
162+
}
163+
validations(orderBy: createdAt, orderDirection: desc) {
164+
validatorAddress
165+
response
166+
status
167+
tag
168+
}
169+
}
170+
}
171+
```
172+
173+
The agent `id` is formatted as `chainId:agentId` (e.g. `8453:1247` for agent 1247 on Base).
174+
175+
### Filter agents by trust model
176+
177+
```graphql
178+
query AgentsByTrust($trustModel: String!) {
179+
agentRegistrationFiles(
180+
where: { supportedTrusts_contains: [$trustModel], active: true }
181+
first: 50
182+
) {
183+
agentId
184+
name
185+
description
186+
supportedTrusts
187+
}
188+
}
189+
```
190+
191+
Common values: `"reputation"`, `"cryptoeconomic"`, `"tee-attestation"`.
192+
193+
### Top-rated feedback across the network
194+
195+
```graphql
196+
query TopFeedback {
197+
feedbacks(
198+
where: { isRevoked: false, value_gte: 1000 }
199+
first: 50
200+
orderBy: value
201+
orderDirection: desc
202+
) {
203+
value
204+
tag1
205+
tag2
206+
agent {
207+
id
208+
registrationFile { name }
209+
}
210+
feedbackFile { text }
211+
}
212+
}
213+
```
214+
215+
## Schema reference
216+
217+
Core entities:
218+
219+
- **`Agent`:** Onchain identity, mutable. Linked to `AgentRegistrationFile`, `Feedback[]`, `Validation[]`, `AgentStats`.
220+
- **`AgentRegistrationFile`:** Immutable, parsed from the IPFS/HTTPS registration URI. Contains all advertised capabilities.
221+
- **`Feedback`:** Onchain feedback entry. Linked to optional `FeedbackFile` for off-chain text and proof of payment.
222+
- **`FeedbackFile`:** Immutable, parsed from the feedback URI.
223+
- **`Validation`:** Validation request and response lifecycle. Status: `PENDING`, `COMPLETED`, `EXPIRED`.
224+
- **`protocolAgentStats`:** Per-agent rollup (total feedback, average score, score distribution).
225+
- **`Protocol`:** Per-chain rollup.
226+
227+
Full schema: [`schema.graphql`](https://github.com/agent0lab/subgraph/blob/main/schema.graphql).
228+
229+
## Resources
230+
231+
- **Agent0 SDK:** TypeScript and Python SDK for ERC-8004 registration, discovery, and reputation: [sdk.ag0.xyz/docs](https://sdk.ag0.xyz/docs)
232+
- **Subgraph repo:** Open-source mappings, schema, and multi-chain deployment config: [github.com/agent0lab/subgraph](https://github.com/agent0lab/subgraph)
233+
- **ERC-8004 spec:** The Trustless Agents standard: [eips.ethereum.org/EIPS/eip-8004](https://eips.ethereum.org/EIPS/eip-8004)
234+
- **Graph Explorer:** Browse all Agent0 Subgraphs: [thegraph.com/explorer?search=agent0](https://thegraph.com/explorer?search=agent0)

0 commit comments

Comments
 (0)