Run an agent generation

POST 
/api/v1/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 /api/v1/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.

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). Poll GET /api/v1/generations/{generation_id} for the result.

400

Bad Request

401

Unauthorized

403

Forbidden

404

Agent or AI provider not found

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 /api/v1/generations/{generation_id}. Streaming requests report the provider error in a terminal SSE frame instead, since their status line is already on the wire.