> ## Documentation Index > Fetch the complete documentation index at: https://docs.budecosystem.com/llms.txt > Use this file to discover all available pages before exploring further. # Task Planner > Let an agent break multi-step work into dependent tasks, track progress, and pick up where it left off ## 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](/prompts-agents/guides/native-tools/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. ```mermaid theme={null} graph LR P[Your system prompt] --> I[+ Task Planner instructions] I --> A[Agent] A -->|bash tool| S[Code Interpreter sandbox] S --> T[taskgraph] T --> D[(Plans in the sandbox)] ``` ## 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. ```markdown theme={null} ## Task Planner You can plan multi-step work with `taskgraph`, a command-line tool installed in your code interpreter sandbox. Run it with the bash tool. ### When to use it Use the planner when a request involves several steps that depend on each other, or when you will be returning to the work later. Skip it for a single question or a one-step task. ### Find the commands Run `taskgraph --help` before your first planner command. It lists every operation. Run `taskgraph --help` for a command's flags. Add `--json -c` when you need to read the output in a later step. ### Important - Other conversations share this sandbox and its plans. Start with `taskgraph init ""`, note the project id it prints (p-...), and pass `--project ` to every command that accepts it. Do not rely on the default project: `init` and `use` change it for every conversation. - Pass `--agent {{AGENT}}` to `go` and to `done --next`. - Save what you found with `taskgraph done --result "..."`. Tasks that depend on it receive the result. - Before you answer, run `taskgraph status --project --detail` and tell the user what is done and what is left. ### Example User: Compare parental leave in Germany and India and draft a note for the HR head. bash: taskgraph init "Parental leave comparison" created p-jndrc8 (Parental leave comparison) bash: taskgraph add --project p-jndrc8 --title "Find Germany parental leave policy" --kind research created task t-yp5zcl (Find Germany parental leave policy) bash: taskgraph add --project p-jndrc8 --title "Find India parental leave policy" --kind research created task t-0yk3ol (Find India parental leave policy) bash: taskgraph add --project p-jndrc8 --title "Draft comparison note for HR head" --dep t-yp5zcl --dep t-0yk3ol created task t-7qs6ts (Draft comparison note for HR head) bash: taskgraph go --project p-jndrc8 --agent {{AGENT}} → t-yp5zcl "Find Germany parental leave policy" [0/3 · 1 ready · 1 blocked] bash: taskgraph done t-yp5zcl --result "14 weeks maternity protection; up to 3 years parental leave per parent" --next --agent {{AGENT}} ✓ t-yp5zcl done → claimed t-0yk3ol "Find India parental leave policy" [1/3 · 1 ready] ``` 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 ` 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](/prompts-agents/guides/native-tools/code-interpreter#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 The sandbox Task Planner runs in How native tools are enabled per prompt version This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.