Run an agent generation

POST 
/v1/projects/:project_id/agents/:agent_id/generate

Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns 202 Accepted with a generation_id to poll via GET /v1/projects/{project_id}/generations/{generation_id}. Pass ?wait=true to block and receive the result inline, where client tools pause the generation and return requires_action. Streaming (stream: true) implies waiting. Pass idempotency_key to make a retry safe: a request whose key is already claimed runs nothing and answers 202 with the generation the key names.

A credential scoped to a project the agent is shared with, through an accepted share, runs it in that project: on the publisher's configuration, recorded, metered and governed in the grantee project.

Request

Responses

200

Generation result or SSE stream (only when ?wait=true or stream: true)

202

Generation accepted and running in the background (default, when wait is omitted or false), or — in every mode, streamed included — a duplicate request: the generation the idempotency_key already names is returned in whatever state it has reached and nothing runs. Poll GET /v1/projects/{project_id}/generations/{generation_id} for the result.

400

Bad Request (e.g. an idempotency_key that is not a non-empty string of at most 255 characters)

401

Unauthorized

403

Forbidden

404

Agent or AI provider not found

409

IDEMPOTENCY_KEY_REUSED — the key is already claimed by a generation started from a different request. Nothing runs.

429

QUOTA_EXCEEDED: an enforce-mode generation quota is exhausted; error.meta carries quota_id, metric, limit, window and resets_at. SHARE_CAP_EXCEEDED: the agent is another project's, reached through a share whose cap is spent for the window; error.meta.retry_after says when. Both carry a Retry-After header.

502

Upstream AI provider error (AI_PROVIDER_ERROR); model output that does not satisfy the agent's output_schema (OUTPUT_SCHEMA_VALIDATION_FAILED — the violated field is named in the message); or a model that wrote a tool invocation out as plain assistant text instead of calling the tool, so the tool never ran (TEXT_ENCODED_TOOL_CALL — meta.tool_name names the tool). 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}. Streaming requests report the provider error in a terminal SSE frame instead, since their status line is already on the wire.