Tasks

A task is saved work attached to an agent. Use tasks when you want repeatable instructions that can run on demand or by trigger.

Create a task

teammate_id is the wire name for the agent id: JSON request and response bodies keep it. The SDK accepts agent_id (canonical) and teammate_id alike.

Key fields

All fields

Field	Type	Description
tools	string[]	Optional override of agent tools
expected_output	string	Output format expectation
goals	string	Task-specific goals injected into prompt context
schedule_timezone	string	Timezone for schedule. Defaults to UTC
enable_lessons	bool	Accumulate lessons from runs. Defaults to true. See Lessons

webhook_enabled is true when a webhook trigger is active. webhook_url is only set on first creation when webhook=True; it's not retrievable afterwards.

Run a task

Approval callbacks, non-streaming runs, tool scoping

run_and_wait() handles approval pauses inline, no polling loop needed. It accepts the same callbacks as runs.create_and_wait(); see Human-in-the-Loop.

Python

Non-streaming:

Python

Pass task_setup_tools=False to keep a run limited to the task's normal tools, skipping the internal same-scope management tools for tasks, runs, inboxes, webhooks, and integrations. Pass feedback=False to disable the internal issue-reporting tool (report_issue).

Scheduling

Pass schedule= at creation time to attach a cron trigger in the same call:

See Scheduling for cron patterns, interval schedules, and pausing or reshaping schedules.

Webhook trigger

Add one to an existing task with client.tasks.triggers.create(task.id, type="webhook"); the returned trigger.url is likewise shown once.

Retrieve a task's results

Every run reports its task (run.task_id) and runs.list filters by it, so a scheduled or webhook-triggered task's history and outputs are one call away:

Failed runs carry a machine-readable error_code plus a human-readable output; retryable=True means client.runs.retry(run.id) will be accepted. Prefer push? Subscribe a webhook endpoint to run.completed / run.failed.

Lessons

Agents save lessons from a task's runs: durable corrections and preferences they apply on future runs, accumulated automatically (capped at 20 per task; disable with enable_lessons=False). The API is the curation surface: read what the agent learned, remove bad entries.

Manage tasks

Next: Runs · Scheduling · Human-in-the-Loop · Webhook Events