Trigger agent generation
POST/v1/projects/:project_id/sessions/:session_id/generate
Triggers the agent to generate a response based on the current conversation. Background by default: returns 202 Accepted with the generation's id once its record exists. Pass ?wait=true to block and receive the assistant reply (or a requires_action status if the agent needs client tool outputs) in the response. Pass stream: true in the body to receive the turn's events as SSE, one frame per step and tool call, until it settles; stream: true with ?wait=false is 400.
Request
Responses
- 200
- 202
- 400
- 401
- 403
- 404
- 409
- 410
- 413
- 429
- 500
- 502
- 4XX
Agent reply or requires_action (only when ?wait=true), or the turn's event stream (with stream: true)
Generation accepted and running in the background (default, when wait is omitted or false). The generation record already exists: poll GET /v1/projects/{project_id}/generations/{generation_id} for it.
The request was malformed or failed validation.
Missing or invalid credentials.
The credential is scoped to a different project, or the caller's role in the project does not carry this action.
The resource does not exist (existence is not leaked).
Generation already in progress
Session has expired due to inactivity
REQUEST_REJECTED — the request body is over the size the body parser accepts
QUOTA_EXCEEDED: an enforce-mode generation quota is exhausted. error.meta carries quota_id, metric, limit, window and resets_at, with a Retry-After header. Only with ?wait=true: a background call is answered 202 before the quota is read.
Unexpected server error — INTERNAL_ERROR, with the raw message never forwarded
Upstream AI provider error (AI_PROVIDER_ERROR). The error meta includes the generation_id and trace_id of the failed generation for post-mortem debugging via GET /v1/projects/{project_id}/generations/{generation_id}.
The deployment's admission service refused this write — answered under the service's own 4xx status, with its code (matching ^[A-Za-z_][A-Za-z0-9_]{0,63}$, not necessarily an ERROR_CODES key), message and meta; the write did not happen. A status this operation also declares on its own is documented there