Build your first agent

An agent is the top-level unit in Rightbrain. It reasons over an input and calls tools to do real work. This quickstart creates an agent, makes the task you built available to it as a tool, runs it over the API, and streams every step. It reuses the RB_TOKEN, RB_ORG, RB_PROJECT, RB_TASK, and RB_MODEL variables from the previous pages.

Step 1: Create the agent

POST to the task-agent endpoint. The instruction is the agent’s standing brief. task_tools attaches your task as a callable tool — with revision_strategy: "follow_active", the tool always runs whatever revision of the task is currently active. Marking a task tool is_output_formatter makes it produce the run’s final structured output.

$
curl -X POST https://app.rightbrain.ai/api/v1/org/$RB_ORG/project/$RB_PROJECT/task-agent \
>
  -H "Authorization: Bearer $RB_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Review Triage Agent",
>
    "instruction": "You triage inbound customer reviews. For each review, use the sentiment tool to classify it, then summarize what the customer is unhappy about and whether it needs escalation.",
>
    "llm_model_id": "'"$RB_MODEL"'",
>
    "max_turns": 10,
>
    "task_tools": [
>
      { "task_id": "'"$RB_TASK"'", "revision_strategy": "follow_active" }
>
    ]
>
  }'

The 201 response is the agent, created with an active revision that snapshots this wiring. Save its id:

$
export RB_AGENT="{agent_id}"

Step 2: Run it and stream the events

Running an agent is different from running a task: an agent takes turns and calls tools, so its run streams back as Server-Sent Events rather than a single response body. Send a message, and pass -N to curl so it doesn’t buffer the stream.

$
curl -N -X POST https://app.rightbrain.ai/api/v1/org/$RB_ORG/project/$RB_PROJECT/task-agent/$RB_AGENT/run \
>
  -H "Authorization: Bearer $RB_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{"message": "Triage this review: My toaster exploded during breakfast and set the bread on fire."}'

Step 3: Follow the stream

Each event is one SSE frame — a data: line with a JSON object, terminated by a blank line. The JSON always carries an event_type. A representative sequence for this agent:

data: {"event_type": "session_id", "metadata": {"session_id": "01909843-3596-da54-4756-28af46917e74"}}
data: {"event_type": "tool_call", "tool_name": "sentiment_analyzer", "tool_display_name": "Sentiment Analyzer", "tool_args": {"customer_review": "My toaster exploded..."}, "tool_call_id": "call_01"}
data: {"event_type": "tool_result", "tool_name": "sentiment_analyzer", "tool_outcome": "success", "tool_call_id": "call_01", "tool_result": {"sentiment": "negative"}}
data: {"event_type": "text", "content": "This review is negative and reports a safety hazard; it should be escalated."}
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}}

The session_id from the first (and done) event lets you continue the conversation: pass it back as session_id on the next run. A run ends in one of running, waiting_for_human, completed, or failed. See Run agents via the API for multi-turn sessions, file inputs, and approval pauses.

Step 4: Fetch the run afterward

The stream is the live view. Every run is also recorded, so you can read a completed run — or its full event transcript — with a plain GET. This is what you reach for when a client disconnected mid-stream, or you need the record later.

$
curl https://app.rightbrain.ai/api/v1/org/$RB_ORG/project/$RB_PROJECT/task-agent/$RB_AGENT/run/{run_id} \
>
  -H "Authorization: Bearer $RB_TOKEN"

$
curl "https://app.rightbrain.ai/api/v1/org/$RB_ORG/project/$RB_PROJECT/task-agent/$RB_AGENT/run/{run_id}/events?include_history=true" \
>
  -H "Authorization: Bearer $RB_TOKEN"

These runs are also visible in your dashboard, but everything you need to run and observe an agent is available over the API.

Where to go next