The API protocol
for intelligent systems
When AI agents need to interact with APIs, GraphQL's self-describing schemas, strong typing, and composable queries make it the natural choice. No hand-written tool definitions. No token-wasting REST payloads. Just structured, predictable data.
- Self-describing schemas let agents discover your API
- Strong typing eliminates hallucinated API calls
- Composable queries minimize token usage by up to 90%
Built for machines
to understand
GraphQL was designed from day one to be machine-readable. Its introspection system, type safety, and composability are the same properties that make it the ideal protocol for AI-agent-to-API communication.
Self-describing
Every GraphQL API ships with a built-in type system. AI agents query `__schema` and immediately understand what data is available, what arguments each field accepts, and how types relate — no hand-written tool descriptions needed.
# Agent introspects your API
query {
__schema {
types {
name
fields {
name
}
}
}
}- Auto-generated tool definitions for LLMs
- Agents discover capabilities at runtime
- Zero-config MCP server from any GraphQL endpoint
Strongly typed
Every field has a known, validated type. LLMs can reason about inputs and outputs with confidence. Structured, predictable responses eliminate parsing errors and prevent hallucinated API calls that plague unstructured REST endpoints.
# Every field has a known type
type Query {
human(id: type">ID!): Human
}
type Human {
name: type">String!
height(unit: Unit): type">Float
}- LLMs understand data shapes natively
- Validated responses prevent parsing errors
- Type system reduces hallucinated API interactions
Composable
Request exactly what you need, nothing more. GraphQL lets AI agents compose precise queries on the fly — requesting nested data, using aliases, and applying filters. One endpoint serves any data access pattern without client-side stitching.
# Agent fetches related data in 1 call
{
human(id: "1000") {
name
friends {
name
starships {
name
}
}
}
}- Up to 90% less token usage vs equivalent REST
- Dynamic query composition by AI agents
- Single endpoint replaces dozens of REST routes
GraphQL vs REST for AI
Where GraphQL pays off when AI agents talk to your API.
Token reduction
GraphQL lets AI agents request only the fields they need. REST endpoints return fixed payloads — often 10x the data an LLM actually needs to process. Every extra token costs money and context window space.
API calls per task
GraphQL's composability means agents can fetch nested, related data in one query. REST requires multiple endpoints, forcing agents to make sequential calls and stitch responses client-side.
Tool definitions
REST frameworks can auto-generate OpenAPI, so this isn't about hand-writing schemas. The edge is plug-and-play: GraphQL's introspection and per-field, per-type, and per-query documentation are built into the spec and discoverable from one endpoint. With REST, an agent needs the API, its schema, and an instruction file (AGENT.md) — and you must point it to each. One GraphQL schema replaces all three.
Type safety
Both are typed — OpenAPI gives REST schemas too. The real difference for agents is traversal: one GraphQL query follows relationships across types, so an agent never needs to hold the entire type graph in context at once. REST splits data across endpoints, forcing agents to remember deep, nested relationships to compose what one field resolves.
| Metric | GraphQL | REST | Why |
|---|---|---|---|
| Token reduction | 90%fewer tokens | 10× moretoken waste | GraphQL lets AI agents request only the fields they need. REST endpoints return fixed payloads — often 10x the data an LLM actually needs to process. Every extra token costs money and context window space. |
| API calls per task | 1single request | 3–7sequential calls | GraphQL's composability means agents can fetch nested, related data in one query. REST requires multiple endpoints, forcing agents to make sequential calls and stitch responses client-side. |
| Tool definitions | 0auto-discovered | 3files to wire | REST frameworks can auto-generate OpenAPI, so this isn't about hand-writing schemas. The edge is plug-and-play: GraphQL's introspection and per-field, per-type, and per-query documentation are built into the spec and discoverable from one endpoint. With REST, an agent needs the API, its schema, and an instruction file (AGENT.md) — and you must point it to each. One GraphQL schema replaces all three. |
| Type safety | 100%typed responses | 100%if used with correct tooling | Both are typed — OpenAPI gives REST schemas too. The real difference for agents is traversal: one GraphQL query follows relationships across types, so an agent never needs to hold the entire type graph in context at once. REST splits data across endpoints, forcing agents to remember deep, nested relationships to compose what one field resolves. |
Both protocols are typed; the gap is in traversal and discoverability, not in whether types exist.
Docs live in the schema — and agents can query them
Descriptions written with """ are stored on the type and every field. An agent reads them back with the built-in __type introspection query — no separate docs file or AGENT.md to point it to.
"""A product in the catalog."""
type Product {
"""Human-readable display name."""
name: type">String!
"""Price in minor units (cents)."""
price: type">Int!
"""Units in stock. 0 means unavailable."""
stock: type">Int!
}
type Query {
"""Full-text search across the catalog."""
products(query: type">String!): [Product!]!
}{
__type(name: "Product") {
description
fields {
name
description
}
}
}{
"__type": {
"description": "A product in the catalog.",
"fields": [
{ "name": "name", "description": "Human-readable display name." },
{ "name": "price", "description": "Price in minor units (cents)." },
{ "name": "stock", "description": "Units in stock. 0 means unavailable." }
]
}
}See GraphQL + AI in action
Pick a prompt below and watch an AI agent introspect the schema, compose a precise GraphQL query, and fetch structured results — all in real time.
Select an example prompt to begin
Watch the AI → GraphQL translation step by step
From natural language
to structured data
Here's what happens when an AI agent uses a GraphQL API to answer a real business question — from initial request to typed response.
Agent receives a task
A user gives an AI agent a natural language instruction — "Show me Q4 revenue by region." The agent needs to access business data through an API to fulfill this request.
> Show me Q4 revenue broken down by region
for the top 5 performing product categoriesAgent introspects the API
Using GraphQL introspection, the agent queries `__schema` and discovers the available types: `Product`, `Order`, `Region`, `RevenueMetrics`. It learns field names, arguments, and relationships automatically.
type Product {
name: type">String!
category: Category!
}
type RevenueMetrics {
amount: type">Float!
region: Region!
}
type Order {
product: Product!
revenue: RevenueMetrics!
}
type Query {
orders(from: Date!, to: Date!): [Order!]!
}Agent composes a query
The LLM maps the user's intent to the discovered schema. It constructs a precise GraphQL query that fetches exactly the right data — revenue by region, top 5 categories, all in a single request — with no over-fetching.
{
orders(from: "2024-10-01", to: "2024-12-31") {
product {
name
category {
name
}
}
revenue {
region {
name
}
amount
}
}
}Structured response returned
The API returns typed, predictable JSON that exactly matches the query shape. The agent processes the results with confidence — every field is validated, every type is known. No parsing ambiguity, no hallucinated or missing fields.
{
"orders": [{
"product": {
"name": "Widget Pro",
"category": {
"name": "Electronics"
}
},
"revenue": {
"region": {
"name": "North America"
},
"amount": 45230.50
}
}]
}GraphQL powers
the AI stack
From MCP servers to RAG pipelines to autonomous agents, GraphQL is already the protocol of choice for connecting AI systems to real data.
MCP Servers
Build Model Context Protocol servers powered by GraphQL. Every query, mutation, and subscription becomes an auto-discoverable tool. Zero hand-written tool definitions — the schema is the contract.
# AI agent discovers and calls tools
query {
tools {
name
description
parameters {
name
type
}
}
}
mutation {
callTool(
name: "searchProducts"
params: { query: "laptop" }
)
}- Auto-generate tool definitions from schema
- Type-safe inputs and structured outputs
- One MCP server exposes your entire API surface
RAG Applications
Power Retrieval-Augmented Generation with GraphQL. Query your knowledge base with precision — fetch documents, embeddings, and cross-references in a single request. No more REST pagination + client-side merging.
{
search(term: "MCP protocol") {
documents {
title
excerpt
embeddings {
vector
similarity
}
}
relatedTopics {
name
}
}
}- Fetch documents + embeddings in one call
- Join data across collections and sources
- Minimize context window waste with field selection
AI Agents & Tool Calling
Give AI agents structured, type-safe access to your data layer. GraphQL's query composition lets LLMs build complex, multi-step data fetches in a single round-trip — calling multiple services, filtering, and aggregating.
{
orders(status: PENDING) {
customer {
name
email
}
items {
product {
name
stock
}
}
total
}
}- Agents compose queries at inference time
- Real-time subscriptions for streaming agents
- Single endpoint for all data operations
Shape the future of
GraphQL & AI
The GraphQL AI Working Group is open to everyone. Help define how GraphQL powers the next generation of intelligent systems — contribute to specs, share use cases, and collaborate with the community.