A presentation at API Superstream by O’Reilly by Lorna Jane Mitchell
API Standards and AI Agents Lorna Mitchell, TM Forum
Standards and AI Agents AI agents discover and call APIs autonomously. • Agents consume documentation as context, and we should assume nothing • Pre-agreed conventions reduce errors and hallucination • We built these foundations without knowing we would need them https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
API Standards https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
HTTP Standards Existing, boring technology is a massive multiplier https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
HTTP Standards HTTP is a great standard: • Envelope format • URLs • Status codes • Encoding/serialising included • Established authentication patterns RESTful design is a strong foundation. https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
API Descriptions Best practice powers up agents, carbon or otherwise https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
OpenAPI The de facto standard for describing HTTP APIs. • Machine-readable YAML or JSON • Huge ecosystem: generators, linters, gateways, portals • Already in the training data • 3.1 uses standard JSON Schema; 3.2 adds agent-enabling features; 3.3 is coming … https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
Better API Descriptions Richer descriptions make for higher quality outcomes. • info.description is for discoverability. What does the API do? • operationId identifies an endpoint, orients agents and links to other contexts. • examples illustrate to audiences what sort of thing they should be aiming for. • externalDocs still matters, agents need context as much as humans. • tags for grouping endpoints in multiple ways. https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
Overlays Augment an API description without modifying the source. • Apply targeted changes over an existing OpenAPI document • Layer AI-specific descriptions and examples on top • Keep the source canonical; add context per consumer • Opportunity for x- extensions for your chosen tools https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
API Description Pipeline An API description is not a static file. • Start with the OpenAPI you already have • Enrich with Overlays: descriptions, examples, AI hints • Validate and lint before publishing • Publish the right topology for each destination (MCP, docs, codegen….) https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
Arazzo Describes multi-step API workflows so agents can complete complex tasks • Links operations across one or more APIs • Captures sequencing, inputs and outputs explicitly • Written for machines to act on, not humans to read https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
Industry Standards Domain-specific integrations designed by industry specialists https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
Industry Standards Competitors become collaborators and provide rich, reusable contexts. • Shared vocabulary so we can communicate effectively • Common scenarios and use cases • Foundational data model fits domain needs • Encodes best practice for ongoing reuse and innovation • Consistency across the standards landscape https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
TM Forum Open APIs TM Forum look after the API standards for Telco: • 700+ member companies collaborating on telecoms APIs • Shared domain model: billing, inventory, ordering and more • OpenAPI descriptions with agreed semantics • Certification programme provides tested, trusted integrations https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
API Standards https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
What To Do Tomorrow These are all achievable. Start somewhere and make an agent happy. • Check your info.description - is it discoverable? • Add or improve operationId on every operation • Add examples that show what good looks like • Describe your multi-step workflows with Arazzo • Pick up OpenAPI 3.2 for modern features and tooling https://lornajane.net ~ https://tmforum.org ~ https://openapis.org
AI is here to stay, and its impact is both wide-ranging across the industry and deep into specific domain spaces. In this session we’ll consider how layered API standards can accelerate agent capabilities — providing consistency of behaviour, a wealth of prior art, and the shared vocabulary that agents need to act reliably. From the standards that built the web through to domain-specific specialised applications, we’ll look at how each layer contributes grounding and context, supporting and magnifying what we can achieve with AI. The session is recommended for API and integration specialists, and anyone who cares about interoperability.
