An agent is a loop: the model decides what to do, your code does it, the result goes back, and it repeats until the job is done. There is no separate agent runtime to install — it is chat completions plus tools plus a loop you control.
No framework required, and none supplied
We do not ship an agent framework. The pieces the API gives you are tool calling, sessions and a tool manifest; the orchestration is ordinary code in your own process, which is where you want your retries, timeouts and permission checks to live anyway.What the platform provides#
| Piece | What it gives you |
|---|---|
| Tool calling | The model asks for a function and arguments; you decide whether to run it. |
| Sessions | Server-side conversation state, so an agent can span processes and restarts. |
| The manifest | A machine-readable description of the hosted tools, for agents that discover capabilities. |
| Structured outputs | A schema-shaped final answer, so the loop terminates in something you can act on. |
Which model#
- Yuva for most agents — parallel tool calls, a large context, and it reads screenshots and documents.
- Rishi when the planning itself is hard, or the agent handles video.
- Bala only for narrow, single-tool loops over text. It calls one tool at a time.
Four rules worth following#
Bound the loop
Always cap the iterations. An agent that keeps calling tools keeps spending credits, and the failure mode is silent — it looks like the job is still running. Eight iterations is generous for most tasks.
Keep the permission check in your code
The model only ever asks. Whether a delete actually runs is decided in your executor, not by how the tool was described. Treat the arguments as untrusted input: they were generated, and they may be wrong.
Feed failures back as results
When a tool throws, return the error as the tool result rather than aborting. The model can usually recover — it will correct an argument and try again — and an aborted loop just hands the user nothing.
Tag the run
Put a chat_ref or an upfyn_tag on every request in a run. When an agent misbehaves you will want to read the whole run back in Logs, and without a tag the turns are scattered among everything else.
Sessions and tool calls are logged together — but only with a session
The Logs page can show you a run's tool calls and system prompts because those come from stored session messages. A raw API call with no session is billed and appears under Generations, but leaves no message trail to inspect. If you want your agent runs to be debuggable after the fact, use a session.The tool loop has a complete, runnable implementation.