> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Tasks

> Rightbrain Tasks are stateless, versioned AI functions with typed inputs and outputs, model selection, fallbacks, A/B revisions, and RAG.

A **Task** is a structured AI function: a prompt with typed inputs, a chosen model, and a typed output. It's stateless and versioned — each run executes one revision without conversation memory.

The easiest way to think about a task: it's a **deterministic agent**. Where an [Agent](/docs/concepts/agents) decides at run time which tools to use and in what order, a task does one well-defined thing, very well, run after run. And like an agent, every task has its **own model**, chosen independently of any agent that calls it — so an agent on a frontier model can delegate, say, classification to a smaller, faster model through a task. When that's all the job needs — a single specialized operation with reliable structured output — use a task directly; you don't need an agent at all.

Tasks are the workhorse primitive. On their own they're callable directly via the API. When you make one available to an agent, it becomes a **tool** the agent can choose to call — its parameters are the `{placeholders}` in its user prompt. Tasks are managed and versioned independently of any agent that uses them.

## When to use a Task

Use a Task when you need one focused LLM operation with a reliable shape: classify, extract, summarize, rewrite, generate an image, transcribe audio. Anything where you want prompt-in, structured-output-out.

Reach for an [Agent](/docs/concepts/agents) instead when the work needs multiple steps, tool calls, or runtime decisions.

## How a Task is structured

A Task is a stable definition; its executable configuration lives in immutable **revisions**.

The **definition** holds durable settings: `name`, `enabled`, `output_modality`, whether it's `public`, whether it's `exposed_to_agents`, and run visibility.

Each **revision** holds the config that actually runs:

* **System and user prompts** — the user prompt supports `{param}` templating; each `{placeholder}` becomes a typed input.
* **Model + fallback** — `llm_model_id` and `llm_config`, plus an optional `fallback_llm_model_id` used if the primary model fails (timeouts excluded). See [Fallbacks & reliability](/docs/production/fallbacks).
* **Output format** — a JSON schema defining the typed output. Each field can be constrained with `options` (a fixed set of allowed values, which acts like an enum on the model's answer) and can nest — a field can be a list of objects, each with its own typed sub-fields. This is how you get reliable structured output instead of prose you have to parse.
* **RAG config** — an optional link to a [Collection](/docs/concepts/collections) for retrieval-augmented runs.
* **MCP tools** — optional `task_mcp_tool_ids` wire tools from a connected MCP server into the task, so it can call an external service mid-run. See [Task-level connections](#task-level-connections).
* **Input processors** and **file input mode** — pre-processing and how uploaded files are accepted. See [Input processors](/docs/concepts/input-processors).

At execution time, Rightbrain adds the Task run's UTC start timestamp to the system context. Relative dates and times are interpreted against that timestamp unless the input supplies another reference date or timezone.

### Output modalities

A Task's `output_modality` is one of `json`, `text`, `image`, `audio`, `pdf`, or `csv`. File outputs (image, audio, pdf, csv) are stored and returned with download URLs on the run.

### Nested and constrained output

Output schemas go as deep as the work needs. A Task that turns a competitor URL into an SEO article outline, for example, can return a list of section objects — each with a `heading_level` constrained by `options` to `h2` or `h3`, and its own sub-list of key points to cover:

```json
{
  "title": { "type": "string" },
  "sections": {
    "type": "list",
    "item_type": "object",
    "nested_structure": {
      "heading": { "type": "string" },
      "heading_level": { "type": "string", "options": ["h2", "h3"] },
      "key_points_to_cover": { "type": "list", "item_type": "string" }
    }
  }
}
```

The model fills the shape you define. Constraining fields with `options` keeps values inside a known set, which is what makes downstream code able to trust the output.

> **Note**
>
> An output schema constrains shape and allowed values; it does not prove that the content is factually correct. Use [Collections](/docs/concepts/collections) for grounding and [evals](/docs/production/evals) for behavior regression checks.

### Revisions and A/B testing

Like agents, Tasks are versioned. An **active revision** serves traffic. You can make **multiple** revisions active at once with a `weight` on each (weights sum to 1.0) to run a weighted **A/B test** — traffic splits across revisions so you can compare prompts or models on live data. See [Versioning & revisions](/docs/production/revisions).

### Task-level connections

External reach isn't agent-only — a Task can carry [Connections](/docs/concepts/connections) itself, no agent in between:

* **Integrations** — as of July 2026, an Integration can attach directly to a Task, so a single task can call a connected service (look something up, post a message) as part of its own run.
* **MCP tools** — tools from a connected MCP server can be wired into a task revision via `task_mcp_tool_ids`. The task's model calls the tool mid-run and shapes the result into the task's typed output — what [Connections](/docs/concepts/connections#direct-vs-task-bound-mcp) calls a **Task-bound MCP** tool.

## Runs

A **run** is one execution: `POST .../task/{id}/run`, as JSON or multipart (for file inputs). The response is the `TaskRun` — the typed output, token counts, timing, credits used, any generated files, and which revision served it (returned in `x-task-revision-id` / `x-task-run-id` headers). Runs are recorded for [observability](/docs/production/observability).

## RAG with Collections

To ground a Task in your own documents, wire a [Collection](/docs/concepts/collections) into the revision's RAG config. At run time the Task retrieves relevant passages and includes them in context — no `{context}` placeholder in your prompt required. A support Task backed by a Collection of return-policy, manual, and warranty documents, for instance, answers "can I return a blender after 45 days?" from your actual policy, and reports back which source chunks it used so you can build a citation UI. This is also how an [Agent](/docs/concepts/agents) gets knowledge-base retrieval — through a Task tool that has a Collection attached.

## Public tasks, sharing, and cloning

* A **public** Task can be run without a credential (the auth check is skipped for `POST .../task/{id}/run` when `public` is true).
* A Task can be **shared** as a public read-only revision snapshot. An authenticated user with create access can **clone** it into another Project. See [Sharing and cloning](/docs/production/sharing).

## Minimal example

Create a Task with one templated input and a typed output, then run it.

**`Create a task`**

```bash title="Create a task"
curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task \
  -H "Authorization: Bearer $RB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sentiment",
    "enabled": true,
    "llm_model_id": "<model-id>",
    "system_prompt": "You are a sentiment analyst.",
    "user_prompt": "Classify the sentiment of this review: {review}",
    "output_format": {
      "sentiment": { "type": "string", "options": ["positive", "neutral", "negative"] },
      "confidence": { "type": "number", "description": "a number between 0 and 1" }
    }
  }'
```

**`Run it`**

```bash title="Run it"
curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run \
  -H "Authorization: Bearer $RB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "task_input": { "review": "Shipping was slow but the product is great." } }'
```

> **Note**
>
> The run body uses `task_input` (not `input_params`). Its keys are the `{placeholders}` from the user prompt.

## Related

#### [Run tasks via API](/docs/api/run-tasks)

Call Tasks over REST, with files and revision selection.

#### [Input processors](/docs/concepts/input-processors)

Transform URLs, documents, audio, and search queries before a Task runs.

#### [Collections](/docs/concepts/collections)

Ground Tasks in your own documents with RAG.

#### [Agents](/docs/concepts/agents)

Make Tasks available for conditional, multi-step work.

#### [API Reference — Tasks](/api-reference/api-reference/tasks)

Full endpoint reference for tasks.