It was evident that GraphQL would be touted as the ultimate API style for agents. After all, it is one of the only ways we expect an API style to stay relevant these days. Whether it is the ideal solution to agent communication is a completely different question.

The Schema

It is true that a schematized API surface, along with introspection capabilities, makes API discovery by agents much more efficient than schema-less alternatives, like reading docs or reading the implementation if they're lucky enough to have access to it.

The thing is GraphQL isn't the only API style with a schema, and some schema approaches are arguably even more metadata-rich, like OpenAPI for example. GraphQL infamously doesn't have a great story yet for schema metadata. (Many of us know this GitHub issue number by heart 😭).

In the end, I think GraphQL's advantage with the schema is one that has always existed with human interactions. GraphQL's schema and implementation are particularly coupled together in most implementations. That is to say that it is very hard to expand or shrink the API surface at runtime without having changed the schema at the same time. That's beautiful when compared to approaches where one has to go to great lengths to ensure the API implementation and schema remain in sync.

So yeah, I do think GraphQL's schema is a powerful tool (always_has_been.png). Is it particularly special for agents? I don't think so, or at least not on its own.

The Query Style

This might be the more interesting point. GraphQL's query language allows clients to query an API's surface in a very flexible way, within the bounds of the schema. Flexibility + safety from the schema sounds like a beautiful combo for an agent caller. I do think that's true, and I think this is where GraphQL starts being quite interesting for working with LLMs.

In my book's introduction, I talk about the beginnings of GraphQL and where its true power lies:

GraphQL’s “engine”, the algorithm that can execute a client’s query against a GraphQL API Schema is in fact kind of our own powerful, yet complex “Client specific server adapter”. A GraphQL API can act as these “BFFs”, but within just one service, because of how decoupled clients can be from how the schema evolves, and how schema developers can add functionality without worrying about adding weight to existing ones.

You might also recall that I often compare GraphQL operations to "client-generated backend resources". I find this is particularly true when using persisted operations. This lets server developers focus on exposing a set of capabilities without having to build client or use-case specific exact implementations, something many of us appreciate at scale.

Let the Agents Cook

Let's push back on this idea for a moment by considering another approach. One could say that for APIs that are internal / where the implementation can be modified by agents, that ability starts losing its beauty. Let's be real, a hand-written API resource for a particular use-case is incredibly hard to beat with something more generic like GraphQL. GraphQL was a trade-off between a completely generic resource-based API and having to write tons of specific and hard to maintain resources. But do LLMs change the picture here? I think they kind of do, but that comes with many challenges like guardrails and ownership. Who owns those client specific endpoints? How do we ensure they stay performant and don't affect other operations on that server? That hasn't changed. What's changed is that it would probably be possible to manage writing and maintaining these client-specific resources.

The Same Old Trade-Off

Could GraphQL's approach still be an appealing trade-off in an agentic world? It appears so to me, at least for now. GraphQL's schema acts as some sort of bounded sandbox within which agents can freely compose queries without going outside the lines. This is a particularly useful property for public APIs, where client agents would never have access to the implementation anyway. For internal APIs where clients could be trusted to make changes, maybe the previous point is a fair pushback. Maybe LLMs are or will be good enough to write their client-specific API resources?

GraphQL for Agents

Anyone who's maintained a GraphQL server for a while knows that safely querying within the bounds of the schema is great in theory — in practice, you're getting paged at 3AM over a catastrophically expensive query that just hit prod.

For humans, what usually needs to be done here is relying on persisted operations and analysis of said operations before they are accepted. For effective agent use of GraphQL, I think that needs to be the workflow too. Agents can attempt to register queries, where a battery of checks are done. This is the perfect opportunity to introduce human oversight too, perhaps adding an approval step at first, maybe removing it once confidence has been built in the operation checks / LLM's approach to querying.

LLMs are good at getting work done, and they'll do it in potentially awful ways. If the API surface is not quite right, we shouldn't be surprised that we receive some weird operations. For example, what if we did not expose a "plural" field to fetch items and an agent requires 10_000 items. You may receive this:

{
  a1: item(id: "1") { a }
  a2: item(id: "2") { a }
  a3: item(id: "3") { a }
  a4: item(id: "4") { a }
  # 10_000 times ...
}

This style of querying can be rejected by your persisted operation workflow, and potentially even feed back into a server-side agent which could improve the schema to accept similar use-cases in a better way. This is again starting to look quite close to letting the agent write its own implementations at this point, but I do think the guardrails / workflows GraphQL enables here are quite interesting.

Is GraphQL the Panacea for Agentic AI?

Not really, no, but it has the potential to be quite good at it. There's much more to be said about GraphQL & LLMs but we'll leave that for another time.

Cheers,

• Marc Twitter/X Linkedin