POST /v1/agents/{agent_id}/run, the response returns immediately with a
task_id and status: "running". The agent is still working in the background. To get
the final result you poll one of the task-read endpoints until status is terminal.
Pick the right endpoint to poll
A typical production loop looks like: poll
/v1/tasks/{task_id} on a backoff schedule;
once status hits a terminal value, call /summary once.
Terminal vs non-terminal statuses
A real polling loop
Cancelling
If you no longer want the result, sendPOST /v1/tasks/{task_id}/cancel. The task moves
to stopped. The step currently executing on the worker is not interrupted; it
finishes naturally, but no further steps are scheduled. Cancel is idempotent: calling on
an already-terminal task returns the current state with 200.
Tasks that legitimately take a long time
Some agents do work that takes minutes (multi-step research, large document extraction). A few rules of thumb:- Keep your client-side timeout generous (≥10 minutes) for those agents.
- Don’t poll faster than every couple of seconds; you won’t get the answer any sooner.
- For very long jobs, persist the
task_idand poll from a background worker, not a user-facing HTTP request.