Deep Tasks

Some jobs are too big for a single chat turn: refactoring a multi-file codebase, producing a report end to end, or analysing a large folder of files. For work like this, your agent can launch a deep task — a background specialist that runs autonomously in the agent’s own sandbox workspace, with full shell, file, and code access. It plans, executes, and iterates on its own, and delivers a final written summary (plus any files it produced) when it finishes.

What a deep task is

A deep task is a long-running background run of an autonomous specialist. It is not another agent on your Agents page — it is a temporary worker your agent spins up for a single assignment:

• It runs in the agent’s sandbox workspace, so it can read and write workspace files, run commands, and execute code.
• It works from a self-contained brief. The specialist does not see the conversation that launched it, so the agent hands it a complete written assignment: the goal, the context, the input files, and what “done” looks like.
• It gets read-only platform tools by default: it can search your knowledge bases and list agents, workflows, and apps, but it cannot change platform data unless write access is explicitly approved (see below).
• It outlives the conversation turn that launched it. Runs take minutes, not seconds, and the result is delivered back into the conversation when the run finishes.

Deep tasks run on the Sonnet model, or Opus for organisations on the Opus tier.

Starting a deep task

You do not launch deep tasks from a page in the portal — you ask your agent, and the agent decides when an assignment is big enough to warrant one. Describe the whole job in one message, the same way you would brief a contractor:

1. Open a chat with the agent that owns the work

   Pick an agent whose workspace holds the relevant files, or your companion agent if you are not sure.

2. Describe the full assignment

   Include the goal, where the inputs live, and what you want produced. The agent turns this into the specialist’s brief, so the more complete your description, the better the outcome.

3. Carry on

   The agent confirms the specialist has started and keeps a quiet status line in the conversation showing what the specialist is currently doing and how long it has been running. You can keep chatting — the run continues in the background, and the final summary arrives as a new message when it is done.

Try asking your agent

“Go through every PDF in the invoices folder, extract the totals into a spreadsheet, and flag anything that does not match the job list.”

“Rebuild the pricing calculator script to handle the new tiers, and write a short doc explaining how it works.”

While a deep task runs you can ask the agent for a progress check at any time, and you can ask it to stop the task if you change your mind. Deep tasks can also be launched without a human present — from a scheduled task, a workflow, or an agent that another agent delegated to.

Budgets and limits

Every deep task runs inside guardrails so a runaway assignment cannot burn through your quota:

• Spend ceiling. Each run has a hard budget measured in weighted tokens. The default ceiling is a generous runaway backstop (10M weighted tokens); the agent can set a lower per-task ceiling for jobs it wants kept cheap (down to a floor of 500K, which covers the fixed startup cost of a run). A run that hits its ceiling is stopped and reported as failed — any partial work stays in the workspace.
• Graceful wind-down. The specialist is kept aware of its remaining budget as it works. Once roughly 80 percent is used, it stops taking on new work and writes a HANDOFF.md file in the working directory capturing what is done, what remains, and how to continue — so a follow-up deep task has a clean starting point instead of an abrupt cutoff.
• Turn cap. Runs are capped at 50 agentic turns by default (100 at most).
• Concurrency. At most two deep tasks can run at the same time per agent. A third start is refused until one finishes or is stopped.
• Billing. Deep-task tokens are metered exactly like the agent’s own model usage and count toward your normal usage and quota.

If a run is interrupted

Deep tasks are resilient to infrastructure restarts. If the container hosting a run is replaced mid-task, the platform automatically relaunches the specialist once, resuming from its saved session transcript — the workspace files and the work done so far are preserved. The status line briefly shows that the task is resuming after a restart. A run only gets one automatic resume: if it dies a second time, or it had already exceeded its budget, it fails for real. Because the specialist writes a HANDOFF.md as its budget runs down, a failed run can usually be continued by launching a fresh deep task that picks up from the handoff.

When a deep task needs write access

By default a specialist can only read platform data. If the brief requires writing it — updating the knowledge base, creating or modifying agents or workflows — the task cannot start until write access is approved:

• You are in the chat. An inline approval card appears in the conversation asking “Approve platform write access for this deep task?”, with the task’s purpose and Approve write access / Reject buttons. Anyone in the conversation can answer, and the specialist starts automatically the moment someone approves.
• No one is in the chat (schedules, workflows, agent-to-agent delegation). Write access is granted automatically — the delegating context is the authorisation, and the grant is recorded for audit.
• Anywhere else. The request lands on the portal Approvals page as a card reading “Deep task wants to write platform data”, showing the requesting agent, the scope, and the purpose. An owner or admin approves or rejects it there. Pending requests expire on their own (one hour by default) if nobody decides.

An approved request is consumed exactly once: the platform mints a single-use, short-lived key scoped to that agent, and the key is revoked when the run ends. See agent-requested write access for how these keys appear alongside your regular API keys.

Caution

Approve write access only when you recognise the task. The card always shows the purpose text from the brief — if it does not match something you or your team asked for, reject it.

The Tasks page

The Tasks page in the sidebar is the portal’s overview of background work: your agents’ schedules, and the execution history of scheduled and on-demand background runs. Each run shows a live status (queued, running, completed, or failed), its start time and duration, and its tool-call and token counts, with filters by status and type. Owners and admins can stop a queued or running execution and expand a run to see its action, result, tool logs, and any error. Deep tasks themselves report progress in the conversation that launched them — the Tasks page is where the rest of your background work lives.

Next steps

• Schedules & Tasks — Recurring background work; a scheduled task can launch a deep task of its own.
• Tools Reference — The deep_task tool alongside everything else your agents can do.
• API Keys — How agent-requested write access relates to your organisation’s MCP keys.
• Companion Agents — The natural place to ask for a deep task when you are not sure which agent should own it.