Save a task and run it again

A saved task is the description of a task — the agent, what it is asked, and the parameters — kept so it can be run again. It runs on demand, and a trigger can point at it instead of carrying its own text. Every run records the saved task it came from in provenance.task_definition_id. In the app they are under Saved tasks.

Prerequisites

An agent with a working model in the workspace.
Permission to run that agent. Running a saved task is a run of its agent, so it needs execute on the agent; saving one does not.
An access token, exported as AGENTAREA_TOKEN, the API base URL as AGENTAREA_URL, and the workspace slug as WORKSPACE.

Steps

Save the task

curl -X POST "$AGENTAREA_URL/v1/workspaces/$WORKSPACE/task-definitions/" \
  -H "Authorization: Bearer $AGENTAREA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Release notes",
    "agent_id": "<agent-id>",
    "description": "Summarise the pull requests merged yesterday.",
    "parameters": {"model_override": "<model-id>"}
  }'

name is 1–255 characters, description is what the agent is asked and must not be blank, and the agent must exist in the workspace. parameters take the same keys as a task’s; delivery_address and session are refused, as on a task.

Run it

curl -X POST "$AGENTAREA_URL/v1/workspaces/$WORKSPACE/task-definitions/$DEFINITION_ID/run" \
  -H "Authorization: Bearer $AGENTAREA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"day": "2026-10-19"}}'

The body is optional; its parameters are merged over the saved ones for this run only. The response is the task, as POST .../agents/{id}/tasks/sync returns it. The run belongs to the caller: provenance.origin_type is user and provenance.source_identity is user:<your id>. A caller without execute on the agent gets 403 and nothing starts.

Point a trigger at it

Pass task_definition_id when creating or updating a trigger of the same agent. Each firing then asks the saved task’s text with its parameters, in place of the trigger’s own task_parameters, so a cron trigger needs no text of its own:

curl -X POST "$AGENTAREA_URL/v1/workspaces/$WORKSPACE/triggers/" \
  -H "Authorization: Bearer $AGENTAREA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-release-notes",
    "agent_id": "<agent-id>",
    "trigger_type": "cron",
    "cron_expression": "0 9 * * 1-5",
    "task_definition_id": "<definition-id>"
  }'

A saved task of another agent, or of another workspace, is refused with 400. Send "task_definition_id": null on an update to go back to the trigger’s own text.

Verify

Every task started from it carries the saved task’s id:

curl -s "$AGENTAREA_URL/v1/workspaces/$WORKSPACE/tasks/" \
  -H "Authorization: Bearer $AGENTAREA_TOKEN" \
  | jq '[.[] | select(.provenance.task_definition_id == "<definition-id>") | {id, status, origin: .provenance.origin_type}]'

A run you started reads origin: "user"; one a trigger fired reads origin: "trigger", with the trigger in provenance.origin_id.

Troubleshooting

Deleting a saved task, or changing its agent, answers 409

Triggers still run it. A trigger was bound to one agent, so the saved task cannot move to another or disappear under it. Point those triggers at another saved task, or send "task_definition_id": null with task_parameters.text, then try again.

Schedule an agent

A cron trigger, its limits, and how to check it fired.

Triggers and channels

What starts a task when nobody is there.

Start here

Concepts

Guides

Self-host

Reference

API reference

API endpoints

Community

Save a task and run it again

Prerequisites

Steps

Save the task

Run it

Point a trigger at it

Verify

Troubleshooting

Schedule an agent

Triggers and channels

​Prerequisites

​Steps

Save the task

Run it

Point a trigger at it

​Verify

​Troubleshooting

​Related

Schedule an agent

Triggers and channels

Prerequisites

Steps

Verify

Troubleshooting

Related