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