Update Task Agent

POST

/org/:org_id/project/:project_id/task-agent/:task_agent_id

POST

/api/v1/org/:org_id/project/:project_id/task-agent/:task_agent_id

$ curl -X POST https://app.rightbrain.ai/api/v1/org/org_id/project/project_id/task-agent/task_agent_id \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "description": "Triages inbound support tickets, drafts a reply, and escalates billing questions.",
>   "max_turns": 12
> }'

1 {
2   "id": "019df849-e106-3301-5894-291b4c9c6cab",
3   "name": "Support Triage Agent",
4   "task_agent_run_visibility": "editors_and_owners",
5   "is_deleted": false,
6   "created": "2026-05-05T10:15:00Z",
7   "modified": "2026-06-12T09:30:00Z",
8   "active_revision": {
9     "id": "019df7a2-44a0-7d66-b496-52c6c197bca1",
10     "task_agent_id": "019df849-e106-3301-5894-291b4c9c6cab",
11     "created": "2026-05-05T10:15:00Z",
12     "modified": "2026-05-05T10:15:00Z"
13   },
14   "revisions": [
15     {
16       "id": "019df849-e12a-b57e-62d4-0e5875e91ef4",
17       "task_agent_id": "019df849-e106-3301-5894-291b4c9c6cab",
18       "description": "Triages inbound client support emails, looks up the client's account, and drafts a reply.",
19       "instruction": "You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message: (1) run the Customer Support Analyzer to classify the sender's sentiment and issue category, (2) look up the client's account in the Customer Database sheet using their email address to confirm their plan, billing status, and any existing notes before you say anything about their account, (3) draft a reply that directly answers what they asked, references specific figures from the account lookup rather than the analyzer's summary, and matches a warm but professional tone, and (4) once a team member confirms the reply, log a one-line resolution note back to the Tickets sheet so the team can see the case was handled. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day. If the account lookup returns no match for the sender's email, say so plainly in the draft and ask the client to confirm the email address on file rather than guessing.",
20       "mode": "agentic",
21       "llm_model_id": "ec217e75-72ea-4281-a1b8-cb7bd0ef9f41",
22       "fallback_llm_model_id": "af2a9bbf-5f36-4b12-bd3f-92c57be96dec",
23       "created": "2026-06-12T09:30:00Z",
24       "llm_model": {
25         "provider": "OpenAI",
26         "vendor": "openai",
27         "name": "gpt-4-turbo",
28         "alias": "GPT-4 Turbo",
29         "description": "Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.",
30         "supports_vision": true,
31         "max_context_window": 128000,
32         "id": "ec217e75-72ea-4281-a1b8-cb7bd0ef9f41",
33         "supports_image_output": false,
34         "supports_pdf_vision": false,
35         "supports_tool_calling": true,
36         "supports_context_caching": false,
37         "price": "average",
38         "speed": "fast",
39         "knowledge_cutoff": "2023-12-01",
40         "created": "2024-01-16T13:33:25.247662Z",
41         "modified": "2024-01-16T13:33:25.247662Z",
42         "llm_model_comments": []
43       },
44       "fallback_llm_model": {
45         "provider": "OpenAI",
46         "vendor": "openai",
47         "name": "gpt-3.5-turbo",
48         "alias": "GPT-3.5 Turbo",
49         "description": "Fast, efficient model suitable for simple tasks. 16K context window.",
50         "supports_vision": false,
51         "max_context_window": 16385,
52         "id": "af2a9bbf-5f36-4b12-bd3f-92c57be96dec",
53         "supports_image_output": false,
54         "supports_pdf_vision": false,
55         "supports_tool_calling": true,
56         "supports_context_caching": false,
57         "price": "cheap",
58         "speed": "standard",
59         "knowledge_cutoff": "2021-09-01",
60         "created": "2024-01-16T13:33:25.247662Z",
61         "modified": "2024-01-16T13:33:25.247662Z",
62         "llm_model_comments": []
63       },
64       "task_tools": [
65         {
66           "id": "019df7a2-44a0-7ee9-8876-25aa7a902f38",
67           "task_id": "019df7a2-44a0-7f6b-8a18-d81df57049d0",
68           "task_name": "Customer Support Analyzer",
69           "order": 0,
70           "enabled": true,
71           "task_revision_id": "019df7a2-44a0-75d6-b036-4e86f6d45302",
72           "revision_strategy": "pinned",
73           "is_output_formatter": false,
74           "action_mode": "auto_run",
75           "rejection_behavior": "end_run"
76         },
77         {
78           "id": "019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb",
79           "task_id": "019df7a2-44a0-7186-92a6-a8e45e78537b",
80           "task_name": "Draft Support Reply",
81           "order": 1,
82           "enabled": true,
83           "task_revision_id": "019df7a2-44a0-78c4-ba7b-6ae382a6253a",
84           "revision_strategy": "pinned",
85           "is_output_formatter": true,
86           "action_mode": "auto_run",
87           "rejection_behavior": "end_run"
88         }
89       ],
90       "integrations": [
91         {
92           "id": "019ebb2a-b9c0-7af9-b42d-e9cd2819667d",
93           "project_integration_id": "019df7a2-44a0-7a75-ae4f-4c8edcdac22e",
94           "integration_type": "google_sheets",
95           "integration_name": "Customer Database",
96           "order": 0,
97           "enabled": true,
98           "provision_source": "manual",
99           "tool_count": 2,
100           "allowed_tool_ids": [
101             "019df7a2-44a0-7b09-afd0-c59cbc20126d",
102             "019df7a2-44a0-7923-9ea9-87be4ba93be9"
103           ],
104           "default_action_mode": "auto_run",
105           "default_rejection_behavior": "end_run",
106           "tool_action_modes": {
107             "019df7a2-44a0-7923-9ea9-87be4ba93be9": "require_approval"
108           },
109           "tool_rejection_behaviors": {}
110         }
111       ],
112       "skills": [],
113       "mcp_servers": [],
114       "registered_tools": [],
115       "tags": [],
116       "max_turns": 50,
117       "active": false,
118       "modified": "2026-06-12T09:30:00Z"
119     },
120     {
121       "id": "019df7a2-44a0-7d66-b496-52c6c197bca1",
122       "task_agent_id": "019df849-e106-3301-5894-291b4c9c6cab",
123       "description": "Triages inbound client support emails and drafts a reply.",
124       "instruction": "You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message, run the Customer Support Analyzer to classify the sender's sentiment and issue category, then draft a reply that directly answers what they asked in a warm but professional tone. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day.",
125       "mode": "agentic",
126       "llm_model_id": "ec217e75-72ea-4281-a1b8-cb7bd0ef9f41",
127       "fallback_llm_model_id": "af2a9bbf-5f36-4b12-bd3f-92c57be96dec",
128       "created": "2026-05-05T10:15:00Z",
129       "llm_model": {
130         "provider": "OpenAI",
131         "vendor": "openai",
132         "name": "gpt-4-turbo",
133         "alias": "GPT-4 Turbo",
134         "description": "Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.",
135         "supports_vision": true,
136         "max_context_window": 128000,
137         "id": "ec217e75-72ea-4281-a1b8-cb7bd0ef9f41",
138         "supports_image_output": false,
139         "supports_pdf_vision": false,
140         "supports_tool_calling": true,
141         "supports_context_caching": false,
142         "price": "average",
143         "speed": "fast",
144         "knowledge_cutoff": "2023-12-01",
145         "created": "2024-01-16T13:33:25.247662Z",
146         "modified": "2024-01-16T13:33:25.247662Z",
147         "llm_model_comments": []
148       },
149       "fallback_llm_model": {
150         "provider": "OpenAI",
151         "vendor": "openai",
152         "name": "gpt-3.5-turbo",
153         "alias": "GPT-3.5 Turbo",
154         "description": "Fast, efficient model suitable for simple tasks. 16K context window.",
155         "supports_vision": false,
156         "max_context_window": 16385,
157         "id": "af2a9bbf-5f36-4b12-bd3f-92c57be96dec",
158         "supports_image_output": false,
159         "supports_pdf_vision": false,
160         "supports_tool_calling": true,
161         "supports_context_caching": false,
162         "price": "cheap",
163         "speed": "standard",
164         "knowledge_cutoff": "2021-09-01",
165         "created": "2024-01-16T13:33:25.247662Z",
166         "modified": "2024-01-16T13:33:25.247662Z",
167         "llm_model_comments": []
168       },
169       "task_tools": [
170         {
171           "id": "019df7a2-44a0-7ee9-8876-25aa7a902f38",
172           "task_id": "019df7a2-44a0-7f6b-8a18-d81df57049d0",
173           "task_name": "Customer Support Analyzer",
174           "order": 0,
175           "enabled": true,
176           "task_revision_id": "019df7a2-44a0-75d6-b036-4e86f6d45302",
177           "revision_strategy": "pinned",
178           "is_output_formatter": false,
179           "action_mode": "auto_run",
180           "rejection_behavior": "end_run"
181         },
182         {
183           "id": "019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb",
184           "task_id": "019df7a2-44a0-7186-92a6-a8e45e78537b",
185           "task_name": "Draft Support Reply",
186           "order": 1,
187           "enabled": true,
188           "task_revision_id": "019df7a2-44a0-78c4-ba7b-6ae382a6253a",
189           "revision_strategy": "pinned",
190           "is_output_formatter": true,
191           "action_mode": "auto_run",
192           "rejection_behavior": "end_run"
193         }
194       ],
195       "integrations": [],
196       "skills": [],
197       "mcp_servers": [],
198       "registered_tools": [],
199       "tags": [],
200       "max_turns": 50,
201       "active": true,
202       "modified": "2026-05-05T10:15:00Z"
203     }
204   ],
205   "shared_with_project": true
206 }

Update Task Agent metadata, create a new revision, or activate an existing revision.

Modifiable fields:

Root metadata: name and run visibility
Revision configuration: description, instruction, LLM models, execution mode, memory settings, task tools, MCP servers, integrations, and skills
Activation: active_revision_id

Updating revision configuration creates a new inactive revision. Activate it with a separate request that only includes active_revision_id.

To update task tools, pass a task_tools array. This performs a full replacement:

Omit the field to leave task tools unchanged
Pass an empty array to remove all task tools
Pass a new array to replace all task tools (array order = execution order)

Example: the response below shows the Support Triage Agent right after adding the Customer Database integration and refining instruction — active_revision still points at the prior revision because activation is a separate call, and the new revision appears in revisions with active: false.

Update Task Agent metadata, create a new revision, or activate an existing revision. Modifiable fields: - Root metadata: name and run visibility - Revision configuration: description, instruction, LLM models, execution mode, memory settings, task tools, MCP servers, integrations, and skills - Activation: `active_revision_id` Updating revision configuration creates a new inactive revision. Activate it with a separate request that only includes `active_revision_id`. To update task tools, pass a `task_tools` array. This performs a full replacement: - Omit the field to leave task tools unchanged - Pass an empty array to remove all task tools - Pass a new array to replace all task tools (array order = execution order) Example: the response below shows the Support Triage Agent right after adding the Customer Database integration and refining `instruction` — `active_revision` still points at the prior revision because activation is a separate call, and the new revision appears in `revisions` with `active: false`.

Authentication

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

Path parameters

org_idstringRequiredformat: "uuid"

The organization ID

project_idstringRequiredformat: "uuid"

The project ID

task_agent_idstringRequiredformat: "uuid"

The task agent ID

Request

This endpoint expects an object.

namestring or nullOptional<=255 characters

descriptionstring or nullOptional

instructionstring or nullOptional

modeenum or nullOptional

Execution mode for TaskAgent.

llm_model_idstring or nullOptionalformat: "uuid"

fallback_llm_model_idstring or nullOptionalformat: "uuid"

task_toolslist of objects or nullOptional

Full replacement of task tools. Omit field to leave task tools unchanged. Pass empty list to remove all task tools.

mcp_serverslist of objects or nullOptional

Full replacement of MCP servers. Omit field to leave unchanged. Pass empty list to remove all.

integrationslist of objects or nullOptional

Full replacement of integrations. Omit field to leave unchanged. Pass empty list to remove all.

skillslist of objects or nullOptional

Full replacement of declarative skills. Omit field to leave unchanged. Pass empty list to remove all.

memory_strategyenum or nullOptional

memory_configmap from strings to any or nullOptional

max_turnsinteger or nullOptional1-500

task_agent_run_visibilityenum or nullOptional

Controls who can see all TaskAgent runs for this agent.

active_revision_idstring or nullOptionalformat: "uuid"

Existing TaskAgent revision to activate. Omit to leave the active revision unchanged.

Response headers

X-New-Revision-IDstringOptional

ID of newly created TaskAgent revision, when the update created one

X-New-Revision-createdstringOptional

Whether a new TaskAgent revision was created

Response

Task Agent updated

idstringformat: "uuid"

namestring

task_agent_run_visibilityenum

is_deletedboolean

createdstring

modifiedstring

active_revisionobject or nullOptional

Summary of the active TaskAgent revision.

revisionslist of objectsOptional

shared_with_projectbooleanOptionalDefaults to false

When true the TaskAgent is shared with members of its Project.

seven_day_summaryobject or nullOptional

Optional summary of visible TaskAgent runs created in the last seven days. Populated when the list endpoint is called with seven_day_summary=true.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

500

Internal Server Error