Tasks

A Task is a structured AI function: a prompt with typed inputs, a chosen model, and a typed output. It’s stateless and versioned — the same input produces a consistent, predictable result, and there’s no drift between runs.

The easiest way to think about a task: it’s a deterministic agent. Where an Agent decides at run time which tools to use and in what order, a task does one well-defined thing, very well, run after run. 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 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.
• 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 for retrieval-augmented runs.
• Input processors and file input mode — pre-processing and how uploaded files are accepted.

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:

1
{
2
  "title": { "type": "string" },
3
  "sections": {
4
    "type": "list",
5
    "item_type": "object",
6
    "nested_structure": {
7
      "heading": { "type": "string" },
8
      "heading_level": { "type": "string", "options": ["h2", "h3"] },
9
      "key_points_to_cover": { "type": "list", "item_type": "string" }
10
    }
11
  }
12
}

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.

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.

Task-level integrations

As of July 2026, Integrations can attach directly to a Task — not only to an agent. A Task can call an external service (for example, look something up in a connected system) as part of its own run.

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.

RAG with Collections

To ground a Task in your own documents, wire a Collection 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 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 view, and others can clone it into their own project.

Minimal example

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

$
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" }
>
    }
>
  }'

Related