A presentation at APIDays London in in London, UK by Lorna Jane Mitchell
API Standards for AI Agents Boring technology, happy agents Lorna Mitchell API Architect, TM Forum
Agents Can’t Ask Questions They only have the context you publish. • Conventions: fewer errors, fewer tokens • Descriptions: the manual the agent reads • Industry standards: a head start on the domain Turns out our oldest standards are brilliant for this. lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Layered context lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Existing, boring technology is a massive multiplier HTTP standards lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Agents Already Speak HTTP Use it properly and they know what to do. • • • • RESTful design: patterns agents already know Headers: retry hints, content types, rate limits OAuth: a login flow the agent already knows .well-known URIs: predictable places to discover things Every deviation is something you have to document. lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
What’s good for humans is good for agents API descriptions lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
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 … lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
The Description Is the API Every gap is a guess the agent has to make. • • • • • info.description: what does the API do? operationId: identifies the endpoint, orients agents examples: show what good looks like externalDocs: context, for agents as much as humans tags: group endpoints in multiple ways lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Fix APIs You Don’t Own Overlays are repeatable OpenAPI transforms. • • • • • Add what’s missing: descriptions, examples, operationIds Remove what agents don’t need: a smaller API to work with Hint your tools: x- extensions for MCP and agent tooling Adapt for each destination: one source, many outputs Re-apply on every upstream update lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
API Description Pipeline One source, many outputs. lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Arazzo: Workflows, Not Endpoints Don’t make the agent guess which call comes next. • Links operations across one or more APIs • Sequencing, inputs and outputs, written down • Built on your operationIds: basics first lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Designed by industry specialists Industry standards: domain-specific integrations lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Industry Standards: Shared Meaning Competitors become collaborators and provide rich, reusable contexts. • • • • Vocabulary: “product” means the same everywhere Data model: the domain, already modelled Scenarios: common use cases, written down Best practice: encoded for reuse, not rediscovered lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
100+ Open APIs The pattern in practice: TM Forum Open APIs • Domain model: billing, inventory, ordering and more • Agreed semantics: in every OpenAPI description • Certification: tested, trusted integrations to check against lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Using an Industry Standard Start from the standard, and make it yours. • • • • Start from its data model, not a blank page Adapt it with Overlays: specialise or filter, don’t fork Test against the conformance suite: guardrails for agents Get involved: standards are shaped by who turns up lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Layered context lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
What To Do Tomorrow These are all achievable. Start somewhere and make an agent happy. • • • • • Use HTTP as intended: standard errors and auth Upgrade OpenAPI: 3.1 or later, not 3.0 Fix your descriptions: operationId, examples, clear text Overlay an API you depend on, yours or not Find your industry’s standard and start from it lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Be conventional. Let the standards do the work. Boring technology, happy agents. lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
Thanks! tmforum.org lornajane.net openapis.org Feedback, please! lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social
