My AI agents keep brute forcing and guessing API interfaces even when specs and documentation are provided.
Even with full API specs, a discovery endpoint, and up-to-date documentation, the agent kept trying random formats, guessing parameters, and doing unnecessary trial and error.
I was able to fine tune the agent client-side and then it worked until the context cleared, but I didn’t want to hard code into context/agents.md how to access an API that will keep changing. I hate all this non-deterministic programming stuff but it's still too good to not do it :)
----> Problem
Anyway, the problem was simple: API responses only returned results, because they adhered to the usual, existing protocols for REST.
There was no structure telling the agent what it should do next. Because of that I constantly had to correct the agent behavior on the client side.
Every time the API specs changed or the agent’s context was cleared, the whole process started again.
----> aaaand, Solution!
That’s what led me to TEKIR.
Project repo:
https://github.com/tangelo-ltd/tekir/
----
TEKIR extends API responses with fields like:
> next_actions
> agent_guidance
> reason
allowing the API to explicitly tell the AI what to do next.
This applies not only to errors, but also to successful responses.
For example, when an order is confirmed the API can guide the agent with instructions like:
>>> "show the user a summary
tracking is not available yet
cancellation is irreversible so ask for confirmation"
Instead of the agent trying to infer the workflow.
----> TEKIR plays well with existing standards.
TEKIR works without breaking existing APIs. It is compatible with RFC 9457 (Problem Details for HTTP APIs) and is language and framework independent.
There is an npm package and Express/Fastify middleware available, but you can also simply drop the markdown spec into your project and tell tools like Claude or Cursor to make the API TEKIR-compatible.
----> There is a different to the existing RFC 9457 (problem details) and HATEOAS
RFC 9457 is very problem-oriented - it explicitly describes errors. TEKIR goes beyond that. It is a guideline for future interactions, somewhat similar to HATEOAS, but with better readability and specifically tailored to automated agents.
---> A little background stuff
Why the name "Tekir"?
"Tekir" is the Turkish word for a tabby cat.
Tabby cats are one of nature’s most resilient designs - mixed genes over thousands of years, street-forged instincts. They evolved beyond survival; they adapt and thrive in almost any environment.
That is the notion I wanted to bring into this dynamic API design as well.
----> I don't think anybody will read up to this point so i feel brave.
There’s also a more personal side to the name.
In January this year my beloved cat Çılgın (which means “crazy” in Turkish) was hit by a car. I couldn’t get it out of my head, so I named this project after him so that in some way his name can live on.
He was a tekir. Extremely independent, very intelligent, and honestly more “human” than most AI systems could ever hope to be, maybe even most humans.
The idea behind the project reflects that spirit: systems that can figure out what to do next without constant supervision.
I also realized the name could work technically as well:
TEKIR - Transparent Endpoint Knowledge for Intelligent Reasoning
---->> The project links
Project page (EN / DE / TR)
https://tangelo-ltd.github.io/tekir/
GitHub
https://github.com/tangelo-ltd/tekir/
I normally don't go out of my way to make a fuzz about such ideas but the recent emergence of tons of tiny ideas into community efforts got my hopes up, would be interesting to know if others building agent-driven systems have run into the same API interaction problems, maybe I'm just "using it wrong".
