API Standards for AI Agents

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