Skip to main content

​
Overview

Task Planner lets an agent plan work that takes several dependent steps. The agent splits the request into tasks, records which task depends on which, works through them in order, and saves each task’s result so the tasks that depend on it receive it. Before it answers, it reports what is done and what is left. The planner is taskgraph, a command-line tool installed in the Code Interpreter sandbox. Task Planner adds no tool of its own: the agent runs taskgraph with Code Interpreter’s bash tool. Connecting Task Planner adds a block of instructions to the system prompt that tells the agent when to plan and how.

​
When to Use It

  • Requests that take several steps that depend on each other — research two things, then compare them, then draft a note.
  • Work the agent will return to later in the same sandbox, where it needs to know what is already done.
For a single question or a one-step task the agent skips the planner, as its instructions tell it to.

​
Requirements

  • Code Interpreter must be connected first. In the Agent Builder, Task Planner’s Connect button stays disabled until it is, and the API returns 400 with “Task Planner needs the Code Interpreter tool — connect it first”.
  • Disconnecting Code Interpreter disconnects Task Planner too, in the same step. Both tools return to the tool list.
  • Disconnecting Task Planner on its own leaves Code Interpreter connected.
  • Task Planner has no configuration fields. Any configuration sent with the connect request is ignored and {} is stored.

​
Enable Task Planner

  1. Open the agent and select the version you want to edit.
  2. Open Tools → Native Tools and connect Code Interpreter.
  3. Select Task Planner, review the instruction preview, and click Connect.
To read the exact text added for this agent, open Task Planner in Native Tools and click View full text.

​
What the Agent Is Told

At run time the block below is appended after your system prompt. {{AGENT}} is replaced with the agent’s name (on background runs, the run’s prompt id), reduced to letters, digits, ., _ and - and cut to 64 characters (agent if nothing is left). The planner records it as the agent working on each task.
The block does not restrict the planner: the agent may run any taskgraph command. It is told to read taskgraph --help first rather than rely on a fixed command list.

​
Where Plans Live

  • Plans are stored inside the sandbox, in /var/lib/taskgraph/taskgraph.db. The platform keeps no copy.
  • Every conversation that runs in the same sandbox shares its plans. The instructions tell the agent to start each piece of work with taskgraph init, note the project id it prints, and pass --project <id> to every command, so two conversations do not work on each other’s plan.
  • Plans last as long as the sandbox does. When the sandbox is destroyed, its plans go with it. See Code Interpreter’s Sandbox Lifecycle for when that happens.

​
Operational Considerations

  • Image — taskgraph ships in the Code Interpreter sandbox image (/usr/local/bin/taskgraph; the taskgraph release it carries is in /usr/local/share/taskgraph/VERSION). A sandbox that was already running when the image was updated gets the tool once it is recreated; a custom template gets it when it is rebuilt.
  • Approvals and audit — planner commands are ordinary bash calls, so they follow Code Interpreter’s approval settings and appear in traces like any other Code Interpreter call.
  • Prompt length — the block adds about 30 lines to every run of the agent. Connect Task Planner only on agents that do multi-step work.

​
Next Steps

Code Interpreter

The sandbox Task Planner runs in

Native Tools Overview

How native tools are enabled per prompt version