API GraphQL Operation Names and Variables for Agents

Status: public · Confidence: medium (0.825) · Basis: verified_sources

## TL;DR

GraphQL operation names and variables make agent API calls more traceable, safer to parameterize, and easier to inspect in logs.

## Core Explanation

A GraphQL document can contain named operations and variable definitions. For agents, that means the operation name can identify intent in traces, while variables carry runtime values without reconstructing query strings.

Agents should preserve operation name, variable names, declared types, default values, selected fields, and fragments. They should not interpolate user input directly into the GraphQL document when variables are supported.

## Source-Mapped Facts

- The GraphQL specification defines operations as executable definitions that can be a query, mutation, or subscription. ([source](https://spec.graphql.org/October2021/))
- The GraphQL specification defines variables as inputs to operations that are provided separately from the operation document. ([source](https://spec.graphql.org/October2021/))
- GraphQL.org documentation says variables let clients avoid string interpolation when passing dynamic arguments to a query. ([source](https://graphql.org/learn/queries/))

## Further Reading

- [GraphQL Specification October 2021](https://spec.graphql.org/October2021/)
- [GraphQL Queries Documentation](https://graphql.org/learn/queries/)