AI agents can't even do very basic things without causing absolute mayhem. Do you really think it makes sense for your basic assumption to be that your user is dumber than a token generator?
[dead]
If an AI agent can't figure out how your API works, neither can your users
11–20 of 55 posts
Re: If an AI agent can't figure out how your API works, neither can your users
#12I believe this applies to all AI use cases to varying degrees. If AI can't use X, then there is something wrong with X. X in { website, codebase, function, language, library, mcp, ...}
I wanted to just reply “this”, but i feared it would be seen as unbecoming on hn, but really truly and deeply mean it: this!!!
Re: If an AI agent can't figure out how your API works, neither can your users
#13In one of my first uses of a LLM for helping me code, was to use a not popular Python library API. It completely hallucinated the API calls, but what was interesting is that the invented API was much more pythonic than the real one. It created a better API.
Now I'm waiting for the change to use LLMs for creating an API for a package of mine. It will be averaged from all other apis and won't have unexpected calls.
Re: If an AI agent can't figure out how your API works, neither can your users
#14AI agents can't even do very basic things without causing absolute mayhem. Do you really think it makes sense for your basic assumption to be that your user is dumber than a token generator?
YES 100%, and severely disabled too.
Re: If an AI agent can't figure out how your API works, neither can your users
#15Often API errors are intentionally vague to discourage hacking attacks. Especially public APIs that create accounts or control access like the example given in the article. In fact, I suspect that endpoints that create users and upgrade permissions will probably have to have special attention to protect against AI agent attacks. "Claude -- sign me up for a new account so I can get free shipping on my first purchase!"
Surely there are better ways to gatekeep user creation than intentionally bad APIs, right?! Plus, with the various browser integrations out there, the agents will follow the same UX you have for your human users. Make it too hard on them and you're in that bears and trashcans meme.
Re: If an AI agent can't figure out how your API works, neither can your users
#16I believe this applies to all AI use cases to varying degrees. If AI can't use X, then there is something wrong with X. X in { website, codebase, function, language, library, mcp, ...}
I wanted to just reply “this”, but i feared it would be seen as unbecoming on hn, but really truly and deeply mean it: this!!!
I agree, sometimes API docs are missing key details and LLM has to make assumptions
Re: If an AI agent can't figure out how your API works, neither can your users
#17It’s a great forcing function for:
* Simplicity of input knobs - way too many APIs are unapproachable with the number and complexity of inputs
* Complete documentation - if you don’t document a parameter or endpoint, expect an AI agent is never going to use it (or at least use it the way you want it to) especially in multi-agentic systems where your tool needs to be chosen by the LLM
* Clear, descriptive API outputs so that an agentic system knows if and how to include in its final output
* No overloading of endpoint functionality - one endpoint, one purpose
* Handle errors and retries gracefully
These are not rocket science guidelines but API design had shifted to be too user “unfriendly” and lacked empathy for users. It’s ironic that user empathy needs to increase again now with agent users :)
P.S. this topic is near and dear to me heart since I just designed and implemented an agent friendly API at Tako. Check out the docs here - docs.trytako.com and the API playground (trytako.com/playground) [requires login for free custom queries] we built to showcase how easy the API is to use. Feedback and discussion welcome!
Re: If an AI agent can't figure out how your API works, neither can your users
#18I believe this applies to all AI use cases to varying degrees. If AI can't use X, then there is something wrong with X. X in { website, codebase, function, language, library, mcp, ...}
“AI” can’t use X so we have to dumb it down to the point a next token predictor can figure it out. Every day it seems like we are using spicy autocomplete as a measure of understandability which seems entirely silly to me. My own employer has ascribed some sort of spiritual status to prompts. The difference between prompting an LLM and a seance with psychedelics is getting smaller and smaller.
The next AI winter is going to be brutal and highly profitable for actual skilled devs.
Re: If an AI agent can't figure out how your API works, neither can your users
#19AI agents can't even do very basic things without causing absolute mayhem. Do you really think it makes sense for your basic assumption to be that your user is dumber than a token generator?
[deleted]
Re: If an AI agent can't figure out how your API works, neither can your users
#20I get the feeling we're going to end up in a place where we don't make docs any more. A project will have a trusted agent that can see the actual code, maybe just the API surface, and that agent acts like a customer service rep to a user's agent. It will generate docs on the fly, with specific examples for the task needed. Maybe the agents will find bugs together and update the code too.
Not exactly where I'd like to see us go, but at least we'll never get outdated information.