Skip to main content
The agent endpoint streams Server-Sent Events. Omit thread_id (or pass null) to start a new conversation; the first conversation_info event carries the assigned thread_id, which you reuse on later turns.
This endpoint consumes LLM credits on every call, and it requires a read,write token.

​
Reading the stream

The stream emits only data: lines. There are no SSE event: lines, so do not key off them: the event kind is the type field inside each JSON payload. Lines beginning with : are keep-alive comments and must be skipped.
Always handle error: it is returned with HTTP 200 inside the stream, because the response has already begun by the time the failure happens. The exact step and artifact shapes are documented in agent-core-logic §7.

​
Choosing a model

A request that omits config runs on the server-side default from llm: in the deployment config. That default is the same model the web UI sends, gemini-2.5-flash, so an API turn and a browser turn are comparable out of the box. To run a different model, pass config:
max_tokens is clamped down to the chosen model’s own output ceiling, so a generous server-side default cannot make a request invalid for a smaller model.
Not every model can drive this agent. Every tool the agent can call carries a required action_and_reasoning argument, which is what produces the user-visible reasoning trace. Smaller models routinely omit it, and because it is required, the tool call fails validation and the agent retries the same call until the turn is exhausted. The symptom is a stream full of action_and_reasoning: Field required errors and no result.gpt-4o-mini fails this way on most tool calls and is not offered in the model picker. If you override config, prefer a frontier model and verify that a tool-using turn actually completes before you rely on it for a batch.