Delivering APIs for AI

My talk for 2024 APIDays Paris https://www.apidays.global/paris/.
Follow up to my 2024 Nordic APIs platform summit talk, this time more hands on. https://speakerdeck.com/zdne/apis-for-ai-have-we-failed

Transcript

1. APIs for AI How to deliver APIs for Agentic AI Zdeněk “Z” Němec, superface.ai, December ’24
2. Zdeněk “Z” Němec • designed an API description language • pioneered API-design & API-first • built APIs with the largest enterprises • building API infrastructure for AI agents • building AI agents Founder and CTO of Superface.ai • DSL director Apiary.io → Oracle • Founder of Good API consulting • Enterprise API strategy and execution superface.ai
3. APIs are enabling AI to take actions superface.ai
4. superface.ai Good APIs can make a dumb AI smarter Poor APIs make any AI fail
5. Three levels of AI maturity Current business drivers for AI are “safe”: Assisting and augmenting workforce superface.ai
6. Superface Agentic AI
7. Agentic AI superface.ai
8. Agentic AI LLM-powered agents • An agent is a software that acts on behalf of user or another program • LLM-powered agents can independently • make decisions • perform tasks • interact with other systems • Agent needs tools to be able to do meaningful things superface.ai
9. Tools Used by agents • Agents are only as good as the tools they have • computation • databases • API calls • LLM works more like a human • It’s able to fi gure out what endpoints to call from API documentation • Agents are more resilient to API changes LLM-powered Agent Memory Planning Tools APIs superface.ai
10. API product & API design are critical for the success of agents
11. Chapter 1: API Product superface.ai
12. You would think the APIs are the best things for agents superface.ai
13. In many situations it is easier, faster and cheaper to access data and perform actions via UI over API. Often, it is the only way. superface.ai
14. LinkedIn A minute vs. several weeks • LinkedIn API exists • It is not easily accessible to developers • The functionality is limited • Using 3rd party (scraping) service • Connect my agent to LinkedIn in one minute superface.ai
15. Accessing a Salesforce instance of a biggest HW maker Deal or no deal • Entering data into CRM • The case was saving 38hrs / week • Agent did not get the API access to the CRM • Entering the data using web actor (scraper) works superface.ai
16. There are many more similar stories • No access to API for agent developers • Legacy APIs (WS/RPC) • API can do only fraction of what UI can superface.ai
17. Chapter 2: API Design superface.ai
18. LLM function calling • Mechanism that LLM uses to recognize a and call a function (tool) • Ideally, we would give an API to LLM and it would fi gure it out • The more atomic and abstract the API is the harder it is to use LLM detects function requirements Structured function input Execution of the function Returning the result API call LLM function calling repeat multiple times superface.ai
19. Documentation Use descriptions to control and hint the LLM: • to pick the tool • what others tools to call • instruct to use fi lters • describe out-of-the-band knowledge Describe everything Example: Salesforce CRM superface.ai
20. Less is more • Return only what is necessary • GraphQL shines here! • Bundle API calls • when descriptions are not enough or context would be too big • Create endpoints to serve speci fi c agentic use-cases • also helps for weaker LLMs Mind the Context Size Example: Google Mail superface.ai
21. Flat parameters are better • Nesting is hard for LLMs • More complex objects can be tough for LLM to correctly fi ll Minimize nesting Example: Google Sheets superface.ai
22. • If your API is abstract agent developers needs to design their tool interfaces • LLM will not fi gure it out Avoid abstraction Extremely di ff i cult for LLMs Example: Notion Notion API: you need to get the database, then blocks in the database, and then iterate through the blocks superface.ai
23. • Return messages relevant to actual error • APIs error handling often sucks • Respect status codes • Most agents can use error message to fi x the request (in 400 cases) • Good error messages are the di ff erence between a failure and success Error handling design it to be useful superface.ai
24. • To prevent hallucinations • Tools need to communicate any relations between parameters • Ideally using JSON Schema (and not description) • Correctly named, described, including format (e.g. timestamps), and default values • De fi ne parameters as enums where possible Required fields must be designed well Example: Scrapin superface.ai
25. • Can take away attention from required fi elds • Not a concern when you are working with one tool Optional fields avoid too many Example: Google Maps superface.ai
26. • Custom GPT limit is 30 • We think the sweet spot is only 15-20 • We are are using hierarchy to fi lter hundreds of tools • Isolated agent can help select the right tool Number of tools keep it very, very low superface.ai
27. What it means for your API? • Follow conventions, don’t get too creative • Keep it simple • Focus on documentation, description and naming • Streamline API access: OIDC/OAuth is a must • Have API AI PO: API- fi rst, API Design for AI superface.ai
28. AI just highlighted the API pains we’ve had for decades. superface.ai
29. Provide Agentic SDK Stripe: API with over 90 endpoints superface.ai
30. APIs are built for the old world • Agents are your new best friends • As API provider / product owner go out and look • The API consumption will be 80% agents and 20% humans superface.ai
31. superface.ai The way humans and software are interacting has changed.
32. Get APIs right or people will either use UI or walk away. ( and agents ) superface.ai
33. Thank you! Let’s talk Zdenek “Z” Nemec 
 Twitter/X: @zdne LinkedIn: https://www.linkedin.com/in/zdne/ superface.ai superface.ai