Run agents via the API

An agent is a goal-directed reasoner that uses the tasks, skills, collections, and connections you’ve made available to it. Running one is different from running a task: an agent takes turns, calls tools, and can pause for approval, so its run streams back as Server-Sent Events rather than returning a single response body.

POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task-agent/{agent_id}/run

The response is a text/event-stream. All requests use bearer authentication — see Authentication.

Request body

You can also select a revision with the revision_id query parameter; otherwise the agent’s active revision is used.

Stream a run

Pass -N to curl so it does not buffer the stream.

$
curl -N -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task-agent/{agent_id}/run \
>
  -H "Authorization: Bearer YOUR_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{"message": "Summarize this month's support tickets and email me the result."}'

The event stream

Each event is one SSE frame: a line beginning with data: followed by a JSON object, terminated by a blank line. The JSON always carries an event_type; the fields populated depend on the type.

A representative sequence:

data: {"event_type": "session_id", "metadata": {"session_id": "01909843-3596-da54-4756-28af46917e74"}}
data: {"event_type": "tool_call", "tool_name": "summarize_tickets", "tool_display_name": "Summarize tickets", "tool_args": {"month": "July"}, "tool_call_id": "call_01"}
data: {"event_type": "tool_result", "tool_name": "summarize_tickets", "tool_outcome": "success", "tool_call_id": "call_01", "tool_result": {"summary": "..."}}
data: {"event_type": "text", "content": "Here is the summary of this month's tickets..."}
data: {"event_type": "formatted_output", "content": "{\"summary\": \"...\", \"top_themes\": [\"billing\", \"latency\"]}"}
data: {"event_type": "done", "metadata": {"run_id": "0195d207-32bb-d03d-cfdc-f4516e9222c8", "session_id": "01909843-3596-da54-4756-28af46917e74", "duration_ms": 8421, "total_tokens": 5120}}

A run ends in one of four statuses: running, waiting_for_human, completed, or failed.

Multi-turn sessions

The first session_id event and the final done event both carry the session ID. Pass it back as session_id on the next run to continue the same conversation with its full history intact.

$
curl -N -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task-agent/{agent_id}/run \
>
  -H "Authorization: Bearer YOUR_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{"message": "Now break that down by product area.", "session_id": "01909843-3596-da54-4756-28af46917e74"}'

Manage sessions directly:

GET     .../task-agent/{agent_id}/session              list sessions
GET     .../task-agent/{agent_id}/session/{session_id} fetch a session
DELETE  .../task-agent/{agent_id}/session/{session_id} delete a session

Approval pauses

If a tool is configured to require approval, the run emits an approval_required event and its status becomes waiting_for_human. The stream ends without a done event; the run resumes once the request is approved, rejected, or resumed. See Approvals (HITL) for the approve/reject/resume endpoints and the full lifecycle.

Attach input files

Send files with a run the same two ways a task does.

1
{
2
  "message": "Analyze this document",
3
  "files": [{ "filename": "report.pdf", "content": "<base64-encoded bytes>" }]
4
}

Retrieve a run after the fact

The stream is the live view. To read a completed run’s events or download files it produced, use the run endpoints — handy when a client disconnected mid-stream or you need the transcript later.

GET  .../task-agent/{agent_id}/run                          list runs (paginated)
GET  .../task-agent/{agent_id}/run/{run_id}                 fetch a run
GET  .../task-agent/{agent_id}/run/{run_id}/events          fetch the run's events
GET  .../task-agent/{agent_id}/run/{run_id}/file/{file_name} download a run file