Speaker
Abstract
Most of what we know about developer experience we learned from humans. Agents are a different user, and some of our best practices quietly work against them.
Your APIs were written for human developers. Agents use them anyway: they skip the docs, guess from training data, and throw calls at your API until something sticks. Every extra turn multiplies failures and hallucinations, and quietly runs up your token bill.
In this session I'll share a framework for measuring how usable an API really is for agents, built on experiments you can rerun on your own APIs. We'll walk through two or three live, I'll hand you seven more to take home, and we'll draw the general conclusions. Fair warning: they overturn sacred cows I've personally taught and defended for more than fifteen years. Accurate documentation is not the be-all-end-all. A machine-readable spec does not automatically make your API agent-ready. And some standard advice on things like idempotency doesn't work the way you think.
What you'll leave with:
- Three widely-believed developer experience best practices that fail for agents, and what to do instead.
- What actually moves agent success rates:
- Naming that leverages everything the model already knows
- Errors designed so an agent recovers on the next try
- Accurate descriptions and schemas
- Code samples/SDKs/Skills over prose and tutorials
- How usability shifts across models and agent types (a coding agent, a chat assistant, and an autonomous agent are three different users), and when to choose APIs, MCP, or CLI, or combine them.
- How to run these experiments yourself, and why no generic checklist or rating tool, mine included, replaces testing with your own use case, agents, and models.
Interview
For more than 15 years I built API products and led product at Apiary and Swagger, tools for better API design, documentation and specs. I was set on exactly what good DX means. Then I watched agents use real APIs, and two of the things I'd spent years improving, docs and specs, weren't enough on their own. So I went into learning mode. I've run more than 300 agent tests against 32 companies' APIs on three models, I advise companies on making their products agent-friendly, and I teach it in hands-on workshops. This session is what I learned, including the parts that surprised me most. It matters for senior developers because you write the standards: the style guide, the API review checklist, the platform templates. If those carry assumptions that only hold for humans, every API your teams ship inherits them.
Because the failures are silent. When an agent can't get your API working, nobody files a support ticket. It works around you, with an old endpoint or a third-party wrapper. In one company's case, agents pointed to unofficial MCP servers in 9 of 11 runs, while the official one sat behind JavaScript they couldn't see. And the ground keeps moving. In March I had a reliable demo of an agent misreading an OpenAPI spec. Today's models rarely miss it. So what was true last quarter may already be wrong, and you only find out by running evals continuously.
Most teams assume that good docs and a complete spec are enough. In my tests, that's where things broke:
- Docs pages that render with JavaScript, so a plain-fetch agent gets an empty shell. On two big, well-known platforms, agents read zero docs text in 30 runs.
- llms.txt files with broken links, or that never mention the company's own MCP server or current API.
- Legacy pages that win search and never point to actual docs. One company's legacy API showed up in 17 of 18 runs.
- Errors like a bare 400 that give the agent nothing to fix.
The hardest part is knowing which of these hurts you. Rating tools disagree with each other. One company got an A+ from one and a D from another.
Test how an agent uses your API. Pick one real task with a known right answer. Give it to the agent your customers actually use, on the smallest model they run, and read the whole transcript. Count the turns, note every guess, and check what it created. Then change one thing, like an error message or a field name, and run it again. 3-10 runs per version are enough to see a pattern. Keep the assertions and the transcripts. That's your first eval, and you can rerun it every time you ship a change or your customers move to a new model.
The bar for practical content. Talks come from practitioners, and vendor pitches are off the table. My track host is a staff engineer, and she held me to concrete takeaways from the first draft. The room is senior engineers and architects who have lived through a few hype cycles and will push back in Q&A. That's exactly who I want to hear from when my findings contradict what I believed for years.
$2,995, Conference (3 days). Current pricing ends November 10th. All pass options.
QCon San Francisco 2026 is a three day conference for senior software engineers, architects and team leads. An international program committee of working engineers selects every session. Patterns and practices, not products and pitches.
Part of the track
Modern API Design for Humans and Agents Hosted by Krys Flores Staff Software Engineer @Crunchyroll, Host of O'Reilly's The Staff Engineer's Career RoadmapFrom the same track
Monday 16 November
10:35 Pacific DEKJ Session APIs That Can't Afford to Be Wrong: Lessons from Moving Money Fawziyah Alebiosu Software Engineer @Imprint Most API design advice assumes a forgiving environment: retries are cheap, data has a single source of truth, and a slow response is only an inconvenience. Financial infrastructure assumes none of that. Card networks give you three seconds to auth or decline. 11:45 Pacific DEKJ Session Everything I Knew About Developer Experience Is Wrong for Agents Emmanuel Paraskakis Founder & CEO @Level 250 Most of what we know about developer experience we learned from humans. Agents are a different user, and some of our best practices quietly work against them. 13:35 Pacific DEKJ Session Developer Experience The Schema Was Never Enough: The World in Protocols Ryan Brown Building infrastructure @Render, Previously Principal @Crunchyroll, @Red Hat, and @Vendia Every reliable process in the world is a protocol: auctions, double-entry bookkeeping, brokerage account transfers, or APIs. Protocols reduce ambiguity but the world remains messy. 14:45 Pacific DEKJ Session No New Backend: The API Layer Behind 800+ Agent-Built Apps at Duolingo Sarah Deitke Senior Software Engineer @Duolingo At Duolingo, anyone (engineer or not) can describe an internal tool and get a working app back, deployed against real company systems. That's BuildingHub, and 350 Duolingo employees have created at least one app with it. 15:55 Seacliff D Unconference Unconference: Modern API Design 17:05 Pacific DEKJ Session Modern APIs Stop Fighting the Remodel: API Design for Models That Outgrew Their Boundaries Aarti Gupta Staff Engineer @Netflix Every domain model has a breaking point. At Netflix, ours arrived all at once—Ads, Games, Live events, and entirely new kinds of content. Each pulled the core entities in different, sometimes contradictory directions.