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
When AI agents interact with APIs, the protocol matters. Here's how GraphQL compares to traditional REST APIs across the metrics that directly impact LLM efficiency and accuracy.
Token reduction
GraphQL
0%
fewer tokens
REST
0×
token waste
Why: 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
0
single request
REST
0
sequential calls
Why: 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
GraphQL
0
auto-discovered
REST
0
files to wire
Why: 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
GraphQL
0%
typed responses
REST
0%
via OpenAPI
Why: 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.
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 or type your own
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.