Build your first agent | Rightbrain Docs — Build reliable AI agents

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.

Need the task first? Follow Create a task, then come back with its id in RB_TASK.

Create, run and observe

Follow the steps beside the code. Paste each shell file’s commands in order into the same terminal; events.txt shows sample output.

Create the agent
The instruction is the agent’s standing brief. task_tools attaches your task as a callable tool. With revision_strategy: "follow_active", it uses the task’s active revision.
The 201 response includes the agent’s id. Save it as RB_AGENT for the next request. These shell commands require jq and run in the same terminal.
A task tool can also use is_output_formatter to produce structured final output, or action_mode: "require_approval" for human sign-off.
Run it and stream the events
Send a review in message. An agent takes turns and calls tools, so the response is Server-Sent Events rather than a single JSON body. -N makes cURL show events as they arrive.
Run this command once to start work. An HTTP success does not guarantee a successful run: inspect the events for done, error, or approval_required.
Follow the stream
This is a representative event sequence; tool names and results depend on your task. Each data: frame contains JSON with an event_type and ends with a blank line.
Save metadata.run_id from done for the next step. Save session_id to continue the conversation by sending it with a subsequent run. An approval_required event pauses work; an error event means the run failed.
Fetch the run afterward
Replace {run_id} with the recorded run ID. Fetch the run for its outcome, then fetch its events for the transcript.
If the stream disconnects before a terminal event, inspect the run before retrying. When no run ID arrived, use the run history endpoints to find it; starting a new run creates new work.

curl --fail-with-body -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" }
    ]
  }' > agent.json &&
export RB_AGENT="$(jq -er .id agent.json)"

Python and TypeScript

To create the same agent from an application, use either example below and save the returned ID as RB_AGENT.

import os, requests
base = f"https://app.rightbrain.ai/api/v1/org/{os.environ['RB_ORG']}/project/{os.environ['RB_PROJECT']}"
headers = {"Authorization": f"Bearer {os.environ['RB_TOKEN']}"}
payload = {
    "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": os.environ["RB_MODEL"],
    "max_turns": 10,
    "task_tools": [
        {"task_id": os.environ["RB_TASK"], "revision_strategy": "follow_active"}
    ],
}
response = requests.post(f"{base}/task-agent", headers=headers, json=payload)
response.raise_for_status()
agent = response.json()
print(agent["id"])

Read the event stream in your application

These readers handle completion, approval pauses, failures and interrupted streams. For multi-turn sessions and file inputs, see Run agents via the API.

Set RB_TOKEN, RB_ORG, RB_PROJECT, and RB_AGENT to your credential and resource IDs. These examples send a review-triage message; change it to match your agent. Python requires httpx; TypeScript uses the built-in fetch in Node.js 22+.

curl --fail-with-body -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" \
  -H "Accept: text/event-stream" \
  -d '{"message": "Triage this review: My toaster exploded during breakfast and set the bread on fire."}'

HTTP success only means the stream opened. The cURL example prints events; its exit code does not tell you whether the agent completed. The Python and TypeScript readers return completed on done, return waiting_for_human on approval_required, and raise an error on a run failure or unexpected end of stream. formatted_output.content is a string; parse it separately if your formatter produces JSON.