How AI agents are changing the way we should build APIs

How AI agents are changing the way we should build APIs

1. How AI agents are changing the way we should build APIs? Fabien Potencier
2. What is an AI Agent? "AI agents are models using tools in a loop" Anthropic "AI agents are autonomous software tools that perform tasks, make decisions, and interact with their environment intelligently and rationally" Github "AI agents are software systems that use AI to pursue goals and complete tasks on behalf of users. They show reasoning, planning, and memory and have a level of autonomy to make decisions, learn, and adapt" Google "An AI agent is a software program that can interact with its environment, collect data, and use that data to perform self-directed tasks that meet predetermined goals. Humans set goals" AWS
3. An AI agent exhibits both machine and human characteristics
4. Who can consume your app? Website Only for humans CLI tool Only for developers API Only for machines (but driven by developers) Semi-private (decoupled frontend) or public
5. Website/CLI tool/API Expose data Allow "users" to act on data Different interface
6. Agents interact with them all! Website LLMs learn by scraping - training :( or live search CLI tool MCP servers can act by running CLI commands API LLM tools are mostly wrappers on top of APIs LLMs can write code that calls APIs
7. From humans (websites) ...to machines (API) ...to AI agents (???) Do AI agents have different expectations for your API?
8. APIs are optimized for machines... • Deterministic • Structured output • HTTP status for errors • Strict inputs ... but machines need a human in the loop to write the code and when something goes wrong AI agents are autonomous
9. Like humans, AI agents need guidance!
10. AI agents need guidance HTTP/2 422 HTTP/2 400 HTTP/2 429 AI agents guess to self-correct
11. AI agents need guidance Thought: I need to get all Upsun projects via their API. I'm going to use GET /projects Action: Call GET /projects Observation: Something went wrong as the API returns 400 Bad request. Thought: I get a 400 Bad request but with no details. I'm not sure why it does not work. Let me check the API documentation. Action: Use the web browser tool to read the latest version of the documentation. Observation: I see that the endpoint is deprecated and that I should call /organizations/{id}/projects now. ...
12. Problem Details for HTTP APIs Error Handling - RFC7807 https://api.platform.sh/projects { "detail" : "Bad Request.", "status" : 400, "title" : "Deprecated endpoint. See https://docs.upsun.com/api/", "type" : "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1" }
13. Problem Details for HTTP APIs Error Handling - RFC7807 https://api.platform.sh/projects { "detail" : "Bad Request.", "status" : 400, "title" : "Deprecated endpoint. See https://docs.upsun.com/api/", "type" : "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1" } [ self::TYPE => $error[self::TYPE] ?? $context[self::TYPE] ?? 'https://tools.ietf.org/html/rfc2616#section-10', self::TITLE => $error[self::TITLE] ?? $context[self::TITLE] ?? 'An error occurred', self::STATUS => $context[self::STATUS] ?? $object->getStatusCode(), 'detail' => $error['detail'] ?? ($debug ? $object->getMessage() : $object->getStatusText()), ]
14. Error Messages Wrong date format for 'date' Quantity too high vs Use the date format YYYY-MM-DD for 'date' Field 'quantity' must be between 1 and 100 Tell AI agents what to do rather than what's wrong
15. Thought: I need to get all Upsun projects via their API. I'm going to use GET /projects Action: Call GET /projects Observation: Something went wrong as the API returns 400 Bad request; I see that the endpoint is deprecated and that there is a new /organizations/{id}/ projects endpoint. Thought: I get a 400 Bad request but with no details. I'm not sure why it does not work. Let me check the API documentation. Action: Use the web browser tool to read the latest version of the documentation. Observation: I see that the endpoint is deprecated and that I should call / organizations/{id}/projects now. Faster, cost effective, less context rot Less round-trips
16. It's all about removing friction Good for both humans and agents
17. Naming things is hard Being consistent is easier https://github.com/symfony/symfony/pull/61743 /repos/{owner}/{repo}/pulls/{pull_number} https://github.com/symfony/symfony/issues/61741 /repos/{owner}/{repo}/issues/{issue_number} user_id vs UserId author_id vs user_id Same or different? Use consistent patterns: APIs should be predictable
18. Like humans, AI agents read documentation!
19. llms.txt / Markdown version of all doc pages (.md) Plain text means less tokens LLMs can parse and understand Markdown hierarchy Copy/paste directly into an LLM context Clear, complete, and up-to-date docs make AI agent succeed more often Document every API endpoint Concise description Flag required/optional inputs Document responses Document all errors, the conditions that trigger them and explain how to fix Inline examples Describe flows Documentation Write unambiguous, comprehensive, and centralized documentation Remove obsolete information, update blog posts, articles, forums, ... Quick-start guides for multi-step flows Avoid misleading agents Avoid frustrating agents Avoid guessing OpenAPI
20. Like humans, AI agents are slow!
21. AI agents are slow Thought: I need to get all Upsun projects via their API. I'm going to use GET /projects Action: Call GET /projects Observation: Something went wrong as the API returns 400 Bad request. Thought: I get a 400 Bad request but with no details. I'm not sure why it does not work. Let me check the API documentation. Action: Use the web browser tool to read the latest version of the documentation. Observation: I see that the endpoint is deprecated and that I should call /organizations/{id}/projects now. ... SLOW FAST SLOW SLOW SLOW Can be avoided SLOW
22. Intent-first API Task oriented Minimize round-trips Minimize payload bloat
23. Like humans, AI agents are non-deterministic!
24. Testing Testing your API with unit tests Testing your UI with Playwright or similar How do you test regression for AI agents?
25. Log everything Segregate agent actions from human/machine actions in your logs to be able to track what they do, when, and why.
26. Like humans, AI agents are expensive!
27. Text vs Tokens https://tiktokenizer.vercel.app
28. Text vs Tokens https://platform.openai.com/tokenizer
29. Text vs Tokens Unique id Date Field name
30. Text vs Tokens gpt-4 codellama
31. Text vs Tokens ISO8601 - 20 tokens RFC2822 - 17 tokens ctime - 14 tokens
32. JSON YAML Markdown
33. AI agents are expensive Thought: I need to get all Upsun projects via their API. I'm going to use GET /projects Action: Call GET /projects Observation: Something went wrong as the API returns 400 Bad request. Thought: I get a 400 Bad request but with no details. I'm not sure why it does not work. Let me check the API documentation. Action: Use the web browser tool to read the latest version of the documentation. Observation: I see that the endpoint is deprecated and that I should call /organizations/{id}/projects now. ... Can be avoided EXPENSIVE CHEAP EXPENSIVE EXPENSIVE EXPENSIVE EXPENSIVE
34. Text vs Tokens Less tokens optimizes the cost but also help with context rot
35. Like humans, AI agents are bad at dealing with credentials!
36. After UX and DX Let's care about AX
37. https://symfony.com/sponsor Sponsor Symfony Thank you!