The API language
for humans and agents
An agent that can reach a GraphQL endpoint can read its types, its field arguments and its documentation, then ask for exactly the fields it needs. Nothing to publish alongside it and keep in sync.
- Self-describing schemas let agents discover your API
- Invalid queries fail validation before they execute
- Field selection keeps responses to what the query asked for
Built for machines
to understand
GraphQL was designed from day one to be machine-readable. Its introspection system, type safety and composability were built for tooling and clients, and they turn out to be what an agent needs to work out what an API offers and ask for part of it.
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.
query {
__schema {
types {
name
fields {
name
}
}
}
}- Auto-generated tool definitions for LLMs
- Agents discover capabilities at runtime
- Generate an MCP server from the schema, not beside it
Strongly typed
Every field has a known, validated type. LLMs can reason about inputs and outputs with confidence. A wrong guess comes back as a named validation error the agent can correct, rather than a 200 with the wrong data in it.
type Query {
human(id: ID!): Human
}
type Human {
name: String!
height(unit: Unit): 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.
{
human(id: "1000") {
name
friends {
name
starships {
name
}
}
}
}- Response size tracks the query, not the endpoint
- Dynamic query composition by AI agents
- One endpoint serves any access pattern the schema allows
What changes when the API describes itself
Both can be typed and both can be documented. The difference is where that description lives, and how much of it an agent has to carry.
| Property | GraphQL | REST + OpenAPI | Why |
|---|---|---|---|
| Discovery | GraphQLIntrospectionfrom the endpoint itself | RESTOpenAPI documentpublished alongside | Most REST frameworks generate an OpenAPI document from the code, so this is not about hand-writing a schema. The difference is that introspection is part of the GraphQL spec and answers on the same endpoint the agent already calls, with no second artifact to locate or keep in sync. |
| Response shape | GraphQLThe query names the fieldscaller decides | RESTThe endpoint decidessparse fieldsets optional | A GraphQL response contains the fields the query asked for. A REST endpoint returns its payload, and narrowing it means a sparse-fieldset convention or another endpoint. An agent pays for the difference in context window. |
| Traversal | GraphQLOne query, many typesfollows relationships | RESTOne endpoint per resourceclient stitches | A GraphQL query walks relationships across types, so the agent never has to hold the whole type graph in context at once. With REST the relationships live in the agent's head, and it composes the result itself. |
| Documentation | GraphQLOn types and fieldsreturned by introspection | RESTIn the spec documentplus an instructions file | Descriptions attach to the type, every field and every argument, and come back through the same introspection call. There is no separate docs file to point the agent at. |
Both protocols are typed, and both can describe themselves. The gap is in traversal and discoverability, not in whether types exist. Where a task maps cleanly onto one purpose-built endpoint, REST is the simpler thing for an agent to call.
The public numbers we can point at come from Apollo, who report around 40% less schema context and 40–75% fewer tool calls when an MCP server exposes a curated set of operations instead of a whole schema. Those are Apollo's own measurements of their own server, not an independent benchmark, and they describe tool selection rather than GraphQL against REST.
If you have reproducible figures for agents against a GraphQL API, the AI Working Group would like to see them, and this page will cite them.
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: String!
"""Price in minor units (cents)."""
price: Int!
"""Units in stock. 0 means unavailable."""
stock: Int!
}
type Query {
"""Full-text search across the catalog."""
products(query: 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 question an agent might get, and see the query it composes against the Star Wars schema. The editor is live: change the query and the response updates.
One query, three inline fragments. `search` returns a union, so each member of the result is matched against the fragments and only the fields named there come back.
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: String!
category: Category!
}
type RevenueMetrics {
amount: 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 response is JSON in the query's shape. A nullable field can still come back null with an `errors` entry, but the agent already knows the shape, so it can use a partial result as-is.
{
"orders": [{
"product": {
"name": "Widget Pro",
"category": {
"name": "Electronics"
}
},
"revenue": {
"region": {
"name": "North America"
},
"amount": 45230.50
}
}]
}GraphQL powers
the AI stack
MCP servers, RAG pipelines and tool-calling agents all need the same two things: a machine-readable description of what data exists, and a way to ask for part of it. A GraphQL schema already provides both.
MCP Servers
Build Model Context Protocol servers powered by GraphQL. Every query, mutation, and subscription becomes an auto-discoverable tool. The schema is the contract, so tool definitions are generated from it rather than maintained beside it.
# 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.