From 87e144a02ddf42620707ccc1e2031945cbd5ceeb Mon Sep 17 00:00:00 2001 From: Shrikar Seshadri Date: Tue, 21 Jul 2026 19:04:23 -0700 Subject: [PATCH 1/8] feat(deepagents)!: make the todo list opt-in Remove `TodoListMiddleware` from the default main-agent, general-purpose subagent, and declarative subagent stacks. Agents no longer receive the `write_todos` tool, the `todos` state channel, or todo prompt text unless the caller opts in via `middleware=[TodoListMiddleware()]`. A caller-supplied instance on the main agent is mirrored onto the auto general-purpose subagent (matched by type, inserted after the core tools and ahead of the caching tail) so the two share a todo list. Declarative subagents opt in through their own spec's `middleware` and do not inherit the main-agent opt-in. The OpenAI Codex profile re-adds it via `extra_middleware` since its system prompt references `write_todos`. Benchmarking found no statistically significant accuracy improvement from `TodoListMiddleware` and higher token usage on two of three models. No public signatures, exports, or serialization formats change. BREAKING CHANGE: agents built without passing `TodoListMiddleware` no longer expose the `write_todos` tool, the `todos` state channel, or the todo-planning prompt section. Pass `middleware=[TodoListMiddleware()]` to restore the previous default. --- libs/deepagents/deepagents/graph.py | 37 ++++--- .../profiles/harness/_openai_codex.py | 22 ++++- .../snapshots/custom_system_message.md | 19 ---- .../custom_system_message_tools.json | 39 -------- .../snapshots/system_prompt_with_execute.md | 19 ---- .../system_prompt_with_execute_tools.json | 39 -------- .../system_prompt_with_media_extra_tools.json | 39 -------- .../system_prompt_with_memory_and_skills.md | 19 ---- ...m_prompt_with_memory_and_skills_tools.json | 39 -------- .../system_prompt_with_routed_backend.md | 19 ---- ...stem_prompt_with_routed_backend_tools.json | 39 -------- .../system_prompt_with_sandbox_default.md | 19 ---- ...em_prompt_with_sync_and_async_subagents.md | 19 ---- ...t_with_sync_and_async_subagents_tools.json | 39 -------- .../system_prompt_without_execute.md | 19 ---- .../system_prompt_without_execute_tools.json | 39 -------- .../tests/unit_tests/test_end_to_end.py | 6 +- .../deepagents/tests/unit_tests/test_graph.py | 99 +++++++++++++++---- libs/deepagents/tests/utils.py | 2 - 19 files changed, 129 insertions(+), 443 deletions(-) diff --git a/libs/deepagents/deepagents/graph.py b/libs/deepagents/deepagents/graph.py index cbb101adb4e..4b5ee4f2a48 100644 --- a/libs/deepagents/deepagents/graph.py +++ b/libs/deepagents/deepagents/graph.py @@ -398,11 +398,15 @@ def create_deep_agent( # noqa: C901, PLR0912, PLR0915 # Complex graph assembly By default, this agent has access to the following tools: - - `write_todos`: manage a todo list - `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`: file operations - `execute`: run shell commands - `task`: call subagents + Todo-list support (the `write_todos` tool) is opt-in: pass + [`TodoListMiddleware`][langchain.agents.middleware.TodoListMiddleware] + via `middleware=` to enable it. When enabled on the main agent it is also + mirrored onto the automatic general-purpose subagent. + The `execute` tool allows running shell commands if the backend implements [`SandboxBackendProtocol`][deepagents.backends.protocol.SandboxBackendProtocol]. For non-sandbox backends, the `execute` tool will return an error message. @@ -440,7 +444,7 @@ def create_deep_agent( # noqa: C901, PLR0912, PLR0915 # Complex graph assembly tools: Additional tools the agent should have access to. These are merged with the built-in tool suite listed above - (`write_todos`, filesystem tools, `execute`, and `task`). + (filesystem tools, `execute`, and `task`). Passing tools here is additive — it never removes a built-in. To drop a built-in tool, register a @@ -466,11 +470,17 @@ def create_deep_agent( # noqa: C901, PLR0912, PLR0915 # Complex graph assembly `SystemMessage` to preserve `cache_control` markers; the result is then a `SystemMessage` whose content blocks are concatenated. middleware: Additional middleware to apply after the base stack - but before the tail middleware. The full ordering is: + but before the tail middleware. + + Todo-list support is opt-in here: passing a + [`TodoListMiddleware`][langchain.agents.middleware.TodoListMiddleware] + instance enables the `write_todos` tool on the main agent and + mirrors it onto the automatic general-purpose subagent. + + The full ordering is: Base stack: - - [`TodoListMiddleware`][langchain.agents.middleware.TodoListMiddleware] - [`SkillsMiddleware`][deepagents.middleware.skills.SkillsMiddleware] (if `skills` is provided) - [`FilesystemMiddleware`][deepagents.middleware.filesystem.FilesystemMiddleware] - [`SubAgentMiddleware`][deepagents.middleware.subagents.SubAgentMiddleware] @@ -761,7 +771,6 @@ class MyState(DeepAgentState): # Build middleware: base stack + skills (if specified) + user's middleware subagent_middleware: list[AgentMiddleware[Any, Any, Any]] = [ - TodoListMiddleware(), FilesystemMiddleware( backend=backend, custom_tool_descriptions=_subagent_profile.tool_description_overrides, @@ -847,7 +856,6 @@ class MyState(DeepAgentState): gp_profile = _profile.general_purpose_subagent or GeneralPurposeSubagentProfile() if gp_profile.enabled is not False and not any(spec["name"] == GENERAL_PURPOSE_SUBAGENT["name"] for spec in inline_subagents): gp_middleware: list[AgentMiddleware[Any, Any, Any]] = [ - TodoListMiddleware(), FilesystemMiddleware( backend=backend, custom_tool_descriptions=_profile.tool_description_overrides, @@ -859,6 +867,10 @@ class MyState(DeepAgentState): if skills is not None: gp_middleware.append(SkillsMiddleware(backend=backend, sources=skills)) + # Core names captured before the tail so an inherited main-agent + # middleware (e.g. an opt-in TodoListMiddleware) splices in after the + # real tools, ahead of the profile/prompt-caching tail. + _gp_core_names = {m.name for m in gp_middleware} # Add harness-profile middleware, if any gp_middleware.extend(_profile.materialize_extra_middleware()) @@ -870,10 +882,13 @@ class MyState(DeepAgentState): matched_classes=_main_matched_classes, matched_names=_main_matched_names, ) - # Inherit only middleware that overrides a default GP slot (including excluded + # Inherit middleware that overrides a default GP slot (including excluded # ones) without carrying over middleware that's specific to the main agent. - _gp_inheritable = [m for m in (middleware or []) if m.name in _gp_original_name_to_index] - gp_middleware = _apply_custom_middleware(gp_middleware, _gp_inheritable) + # TodoListMiddleware is a special case: it is no longer a GP default, but a + # caller-supplied instance on the main agent is mirrored here so the todo + # list is shared between the main agent and the general-purpose subagent. + _gp_inheritable = [m for m in (middleware or []) if m.name in _gp_original_name_to_index or isinstance(m, TodoListMiddleware)] + gp_middleware = _apply_custom_middleware(gp_middleware, _gp_inheritable, core_names=_gp_core_names) gp_middleware = _apply_excluded_middleware( gp_middleware, _profile, @@ -912,9 +927,7 @@ class MyState(DeepAgentState): inline_subagents.insert(0, general_purpose_spec) # Build main agent middleware stack - deepagent_middleware: list[AgentMiddleware[Any, Any, Any]] = [ - TodoListMiddleware(), - ] + deepagent_middleware: list[AgentMiddleware[Any, Any, Any]] = [] if skills is not None: deepagent_middleware.append(SkillsMiddleware(backend=backend, sources=skills)) deepagent_middleware.append( diff --git a/libs/deepagents/deepagents/profiles/harness/_openai_codex.py b/libs/deepagents/deepagents/profiles/harness/_openai_codex.py index 315c2989b25..794207e51fa 100644 --- a/libs/deepagents/deepagents/profiles/harness/_openai_codex.py +++ b/libs/deepagents/deepagents/profiles/harness/_openai_codex.py @@ -14,6 +14,11 @@ non-Codex OpenAI models unchanged. """ +from typing import Any + +from langchain.agents.middleware import TodoListMiddleware +from langchain.agents.middleware.types import AgentMiddleware + from deepagents.profiles.harness.harness_profiles import ( HarnessProfile, _register_harness_profile_impl, @@ -61,8 +66,23 @@ """Text appended to the assembled base system prompt.""" +def _build_extra_middleware() -> list[AgentMiddleware[Any, Any, Any]]: + """Build fresh Codex behavioral middleware for each assembled agent stack. + + Includes `TodoListMiddleware` (the `write_todos` tool) since the Codex + system prompt references reconciling TODO/plan items via `write_todos`; the + SDK no longer provides it by default. A fresh instance per stack avoids + sharing state across stacks. + """ + middleware: list[AgentMiddleware[Any, Any, Any]] = [TodoListMiddleware()] + return middleware + + def register() -> None: """Register the built-in Codex harness profile for each Codex spec.""" - profile = HarnessProfile(system_prompt_suffix=_SYSTEM_PROMPT_SUFFIX) + profile = HarnessProfile( + system_prompt_suffix=_SYSTEM_PROMPT_SUFFIX, + extra_middleware=_build_extra_middleware, + ) for spec in _CODEX_MODEL_SPECS: _register_harness_profile_impl(spec, profile) diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message.md b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message.md index 48bc52973fc..23fcbd6f100 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message.md +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message.md @@ -44,25 +44,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message_tools.json b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message_tools.json index d5a43ebe600..dbf9d68fdd8 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message_tools.json +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/custom_system_message_tools.json @@ -1,43 +1,4 @@ [ - { - "function": { - "description": "Use this tool to create and manage a structured task list for your current work session. This helps you track progress and organize complex tasks.\n\nOnly use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.\n\n## When to Use This Tool\n\nUse this tool in these scenarios:\n\n1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n3. User explicitly requests todo list - When the user directly asks you to use the todo list\n4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n5. The plan may need future revisions or updates based on results from the first few steps\n\n## How to Use This Tool\n\n1. When you start working on a task - Mark it as in_progress BEFORE beginning work.\n2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.\n3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.\n4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.\n\n## When NOT to Use This Tool\n\nIt is important to skip using this tool when:\n1. There is only a single, straightforward task\n2. The task is trivial and tracking it provides no benefit\n3. The task can be completed in less than 3 trivial steps\n4. The task is purely conversational or informational\n\n## Task States and Management\n\n1. **Task States**: Use these states to track progress:\n - pending: Task not yet started\n - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)\n - completed: Task finished successfully\n\n2. **Task Management**:\n - Update task status in real-time as you work\n - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n - Complete current tasks before starting new ones\n - Remove tasks that are no longer relevant from the list entirely\n - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.\n - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress.\n\n3. **Task Completion Requirements**:\n - ONLY mark a task as completed when you have FULLY accomplished it\n - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n - When blocked, create a new task describing what needs to be resolved\n - Never mark a task as completed if:\n - There are unresolved issues or errors\n - Work is partial or incomplete\n - You encountered blockers that prevent completion\n - You couldn't find necessary resources or dependencies\n - Quality standards haven't been met\n\n4. **Task Breakdown**:\n - Create specific, actionable items\n - Break complex tasks into smaller, manageable steps\n - Use clear, descriptive task names\n\nBeing proactive with task management ensures you complete all requirements successfully\nRemember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all.\n\n## When You Finish\n\n`write_todos` tracks your work; it does not deliver the answer. Whatever the user asked for \u2014 computations, summaries, comparisons, data \u2014 must appear as text content in a message after your final `write_todos` call. Marking the last todo complete is not itself an answer to the user.", - "name": "write_todos", - "parameters": { - "properties": { - "todos": { - "items": { - "description": "A single todo item with content and status.", - "properties": { - "content": { - "type": "string" - }, - "status": { - "enum": [ - "pending", - "in_progress", - "completed" - ], - "type": "string" - } - }, - "required": [ - "content", - "status" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "todos" - ], - "type": "object" - } - }, - "type": "function" - }, { "function": { "description": "Lists all files in a directory.\n\nThis is useful for exploring the filesystem and finding the right file to read or edit.\nYou should almost ALWAYS use this tool before using the read_file or edit_file tools.", diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute.md b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute.md index 91055b8c2d8..391bdaade39 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute.md +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute_tools.json b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute_tools.json index 068095f54cb..fdb2c9d6812 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute_tools.json +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_execute_tools.json @@ -1,43 +1,4 @@ [ - { - "function": { - "description": "Use this tool to create and manage a structured task list for your current work session. This helps you track progress and organize complex tasks.\n\nOnly use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.\n\n## When to Use This Tool\n\nUse this tool in these scenarios:\n\n1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n3. User explicitly requests todo list - When the user directly asks you to use the todo list\n4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n5. The plan may need future revisions or updates based on results from the first few steps\n\n## How to Use This Tool\n\n1. When you start working on a task - Mark it as in_progress BEFORE beginning work.\n2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.\n3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.\n4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.\n\n## When NOT to Use This Tool\n\nIt is important to skip using this tool when:\n1. There is only a single, straightforward task\n2. The task is trivial and tracking it provides no benefit\n3. The task can be completed in less than 3 trivial steps\n4. The task is purely conversational or informational\n\n## Task States and Management\n\n1. **Task States**: Use these states to track progress:\n - pending: Task not yet started\n - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)\n - completed: Task finished successfully\n\n2. **Task Management**:\n - Update task status in real-time as you work\n - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n - Complete current tasks before starting new ones\n - Remove tasks that are no longer relevant from the list entirely\n - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.\n - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress.\n\n3. **Task Completion Requirements**:\n - ONLY mark a task as completed when you have FULLY accomplished it\n - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n - When blocked, create a new task describing what needs to be resolved\n - Never mark a task as completed if:\n - There are unresolved issues or errors\n - Work is partial or incomplete\n - You encountered blockers that prevent completion\n - You couldn't find necessary resources or dependencies\n - Quality standards haven't been met\n\n4. **Task Breakdown**:\n - Create specific, actionable items\n - Break complex tasks into smaller, manageable steps\n - Use clear, descriptive task names\n\nBeing proactive with task management ensures you complete all requirements successfully\nRemember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all.\n\n## When You Finish\n\n`write_todos` tracks your work; it does not deliver the answer. Whatever the user asked for \u2014 computations, summaries, comparisons, data \u2014 must appear as text content in a message after your final `write_todos` call. Marking the last todo complete is not itself an answer to the user.", - "name": "write_todos", - "parameters": { - "properties": { - "todos": { - "items": { - "description": "A single todo item with content and status.", - "properties": { - "content": { - "type": "string" - }, - "status": { - "enum": [ - "pending", - "in_progress", - "completed" - ], - "type": "string" - } - }, - "required": [ - "content", - "status" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "todos" - ], - "type": "object" - } - }, - "type": "function" - }, { "function": { "description": "Lists all files in a directory.\n\nThis is useful for exploring the filesystem and finding the right file to read or edit.\nYou should almost ALWAYS use this tool before using the read_file or edit_file tools.", diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_media_extra_tools.json b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_media_extra_tools.json index 59f5eaacc20..c2026491a99 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_media_extra_tools.json +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_media_extra_tools.json @@ -1,43 +1,4 @@ [ - { - "function": { - "description": "Use this tool to create and manage a structured task list for your current work session. This helps you track progress and organize complex tasks.\n\nOnly use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.\n\n## When to Use This Tool\n\nUse this tool in these scenarios:\n\n1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n3. User explicitly requests todo list - When the user directly asks you to use the todo list\n4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n5. The plan may need future revisions or updates based on results from the first few steps\n\n## How to Use This Tool\n\n1. When you start working on a task - Mark it as in_progress BEFORE beginning work.\n2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.\n3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.\n4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.\n\n## When NOT to Use This Tool\n\nIt is important to skip using this tool when:\n1. There is only a single, straightforward task\n2. The task is trivial and tracking it provides no benefit\n3. The task can be completed in less than 3 trivial steps\n4. The task is purely conversational or informational\n\n## Task States and Management\n\n1. **Task States**: Use these states to track progress:\n - pending: Task not yet started\n - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)\n - completed: Task finished successfully\n\n2. **Task Management**:\n - Update task status in real-time as you work\n - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n - Complete current tasks before starting new ones\n - Remove tasks that are no longer relevant from the list entirely\n - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.\n - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress.\n\n3. **Task Completion Requirements**:\n - ONLY mark a task as completed when you have FULLY accomplished it\n - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n - When blocked, create a new task describing what needs to be resolved\n - Never mark a task as completed if:\n - There are unresolved issues or errors\n - Work is partial or incomplete\n - You encountered blockers that prevent completion\n - You couldn't find necessary resources or dependencies\n - Quality standards haven't been met\n\n4. **Task Breakdown**:\n - Create specific, actionable items\n - Break complex tasks into smaller, manageable steps\n - Use clear, descriptive task names\n\nBeing proactive with task management ensures you complete all requirements successfully\nRemember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all.\n\n## When You Finish\n\n`write_todos` tracks your work; it does not deliver the answer. Whatever the user asked for \u2014 computations, summaries, comparisons, data \u2014 must appear as text content in a message after your final `write_todos` call. Marking the last todo complete is not itself an answer to the user.", - "name": "write_todos", - "parameters": { - "properties": { - "todos": { - "items": { - "description": "A single todo item with content and status.", - "properties": { - "content": { - "type": "string" - }, - "status": { - "enum": [ - "pending", - "in_progress", - "completed" - ], - "type": "string" - } - }, - "required": [ - "content", - "status" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "todos" - ], - "type": "object" - } - }, - "type": "function" - }, { "function": { "description": "Lists all files in a directory.\n\nThis is useful for exploring the filesystem and finding the right file to read or edit.\nYou should almost ALWAYS use this tool before using the read_file or edit_file tools.", diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills.md b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills.md index b40b45a331f..8c5422663b7 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills.md +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Skills System You have access to a skills library that provides specialized capabilities and domain knowledge. diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills_tools.json b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills_tools.json index d5a43ebe600..dbf9d68fdd8 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills_tools.json +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_memory_and_skills_tools.json @@ -1,43 +1,4 @@ [ - { - "function": { - "description": "Use this tool to create and manage a structured task list for your current work session. This helps you track progress and organize complex tasks.\n\nOnly use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.\n\n## When to Use This Tool\n\nUse this tool in these scenarios:\n\n1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n3. User explicitly requests todo list - When the user directly asks you to use the todo list\n4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n5. The plan may need future revisions or updates based on results from the first few steps\n\n## How to Use This Tool\n\n1. When you start working on a task - Mark it as in_progress BEFORE beginning work.\n2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.\n3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.\n4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.\n\n## When NOT to Use This Tool\n\nIt is important to skip using this tool when:\n1. There is only a single, straightforward task\n2. The task is trivial and tracking it provides no benefit\n3. The task can be completed in less than 3 trivial steps\n4. The task is purely conversational or informational\n\n## Task States and Management\n\n1. **Task States**: Use these states to track progress:\n - pending: Task not yet started\n - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)\n - completed: Task finished successfully\n\n2. **Task Management**:\n - Update task status in real-time as you work\n - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n - Complete current tasks before starting new ones\n - Remove tasks that are no longer relevant from the list entirely\n - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.\n - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress.\n\n3. **Task Completion Requirements**:\n - ONLY mark a task as completed when you have FULLY accomplished it\n - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n - When blocked, create a new task describing what needs to be resolved\n - Never mark a task as completed if:\n - There are unresolved issues or errors\n - Work is partial or incomplete\n - You encountered blockers that prevent completion\n - You couldn't find necessary resources or dependencies\n - Quality standards haven't been met\n\n4. **Task Breakdown**:\n - Create specific, actionable items\n - Break complex tasks into smaller, manageable steps\n - Use clear, descriptive task names\n\nBeing proactive with task management ensures you complete all requirements successfully\nRemember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all.\n\n## When You Finish\n\n`write_todos` tracks your work; it does not deliver the answer. Whatever the user asked for \u2014 computations, summaries, comparisons, data \u2014 must appear as text content in a message after your final `write_todos` call. Marking the last todo complete is not itself an answer to the user.", - "name": "write_todos", - "parameters": { - "properties": { - "todos": { - "items": { - "description": "A single todo item with content and status.", - "properties": { - "content": { - "type": "string" - }, - "status": { - "enum": [ - "pending", - "in_progress", - "completed" - ], - "type": "string" - } - }, - "required": [ - "content", - "status" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "todos" - ], - "type": "object" - } - }, - "type": "function" - }, { "function": { "description": "Lists all files in a directory.\n\nThis is useful for exploring the filesystem and finding the right file to read or edit.\nYou should almost ALWAYS use this tool before using the read_file or edit_file tools.", diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_routed_backend.md b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_routed_backend.md index 02d48606344..2b66ffad17d 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_routed_backend.md +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_routed_backend.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_routed_backend_tools.json b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_routed_backend_tools.json index 068095f54cb..fdb2c9d6812 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_routed_backend_tools.json +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_routed_backend_tools.json @@ -1,43 +1,4 @@ [ - { - "function": { - "description": "Use this tool to create and manage a structured task list for your current work session. This helps you track progress and organize complex tasks.\n\nOnly use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.\n\n## When to Use This Tool\n\nUse this tool in these scenarios:\n\n1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n3. User explicitly requests todo list - When the user directly asks you to use the todo list\n4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n5. The plan may need future revisions or updates based on results from the first few steps\n\n## How to Use This Tool\n\n1. When you start working on a task - Mark it as in_progress BEFORE beginning work.\n2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.\n3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.\n4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.\n\n## When NOT to Use This Tool\n\nIt is important to skip using this tool when:\n1. There is only a single, straightforward task\n2. The task is trivial and tracking it provides no benefit\n3. The task can be completed in less than 3 trivial steps\n4. The task is purely conversational or informational\n\n## Task States and Management\n\n1. **Task States**: Use these states to track progress:\n - pending: Task not yet started\n - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)\n - completed: Task finished successfully\n\n2. **Task Management**:\n - Update task status in real-time as you work\n - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n - Complete current tasks before starting new ones\n - Remove tasks that are no longer relevant from the list entirely\n - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.\n - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress.\n\n3. **Task Completion Requirements**:\n - ONLY mark a task as completed when you have FULLY accomplished it\n - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n - When blocked, create a new task describing what needs to be resolved\n - Never mark a task as completed if:\n - There are unresolved issues or errors\n - Work is partial or incomplete\n - You encountered blockers that prevent completion\n - You couldn't find necessary resources or dependencies\n - Quality standards haven't been met\n\n4. **Task Breakdown**:\n - Create specific, actionable items\n - Break complex tasks into smaller, manageable steps\n - Use clear, descriptive task names\n\nBeing proactive with task management ensures you complete all requirements successfully\nRemember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all.\n\n## When You Finish\n\n`write_todos` tracks your work; it does not deliver the answer. Whatever the user asked for \u2014 computations, summaries, comparisons, data \u2014 must appear as text content in a message after your final `write_todos` call. Marking the last todo complete is not itself an answer to the user.", - "name": "write_todos", - "parameters": { - "properties": { - "todos": { - "items": { - "description": "A single todo item with content and status.", - "properties": { - "content": { - "type": "string" - }, - "status": { - "enum": [ - "pending", - "in_progress", - "completed" - ], - "type": "string" - } - }, - "required": [ - "content", - "status" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "todos" - ], - "type": "object" - } - }, - "type": "function" - }, { "function": { "description": "Lists all files in a directory.\n\nThis is useful for exploring the filesystem and finding the right file to read or edit.\nYou should almost ALWAYS use this tool before using the read_file or edit_file tools.", diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sandbox_default.md b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sandbox_default.md index e2e4211d8a2..6e1765226b1 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sandbox_default.md +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sandbox_default.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents.md b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents.md index ae0d97002cb..444329ee26c 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents.md +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents_tools.json b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents_tools.json index eba520dc866..0bde4563806 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents_tools.json +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sync_and_async_subagents_tools.json @@ -1,43 +1,4 @@ [ - { - "function": { - "description": "Use this tool to create and manage a structured task list for your current work session. This helps you track progress and organize complex tasks.\n\nOnly use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.\n\n## When to Use This Tool\n\nUse this tool in these scenarios:\n\n1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n3. User explicitly requests todo list - When the user directly asks you to use the todo list\n4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n5. The plan may need future revisions or updates based on results from the first few steps\n\n## How to Use This Tool\n\n1. When you start working on a task - Mark it as in_progress BEFORE beginning work.\n2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.\n3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.\n4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.\n\n## When NOT to Use This Tool\n\nIt is important to skip using this tool when:\n1. There is only a single, straightforward task\n2. The task is trivial and tracking it provides no benefit\n3. The task can be completed in less than 3 trivial steps\n4. The task is purely conversational or informational\n\n## Task States and Management\n\n1. **Task States**: Use these states to track progress:\n - pending: Task not yet started\n - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)\n - completed: Task finished successfully\n\n2. **Task Management**:\n - Update task status in real-time as you work\n - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n - Complete current tasks before starting new ones\n - Remove tasks that are no longer relevant from the list entirely\n - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.\n - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress.\n\n3. **Task Completion Requirements**:\n - ONLY mark a task as completed when you have FULLY accomplished it\n - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n - When blocked, create a new task describing what needs to be resolved\n - Never mark a task as completed if:\n - There are unresolved issues or errors\n - Work is partial or incomplete\n - You encountered blockers that prevent completion\n - You couldn't find necessary resources or dependencies\n - Quality standards haven't been met\n\n4. **Task Breakdown**:\n - Create specific, actionable items\n - Break complex tasks into smaller, manageable steps\n - Use clear, descriptive task names\n\nBeing proactive with task management ensures you complete all requirements successfully\nRemember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all.\n\n## When You Finish\n\n`write_todos` tracks your work; it does not deliver the answer. Whatever the user asked for \u2014 computations, summaries, comparisons, data \u2014 must appear as text content in a message after your final `write_todos` call. Marking the last todo complete is not itself an answer to the user.", - "name": "write_todos", - "parameters": { - "properties": { - "todos": { - "items": { - "description": "A single todo item with content and status.", - "properties": { - "content": { - "type": "string" - }, - "status": { - "enum": [ - "pending", - "in_progress", - "completed" - ], - "type": "string" - } - }, - "required": [ - "content", - "status" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "todos" - ], - "type": "object" - } - }, - "type": "function" - }, { "function": { "description": "Lists all files in a directory.\n\nThis is useful for exploring the filesystem and finding the right file to read or edit.\nYou should almost ALWAYS use this tool before using the read_file or edit_file tools.", diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute.md b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute.md index 82465d72927..94379789b18 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute.md +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute_tools.json b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute_tools.json index d5a43ebe600..dbf9d68fdd8 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute_tools.json +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_without_execute_tools.json @@ -1,43 +1,4 @@ [ - { - "function": { - "description": "Use this tool to create and manage a structured task list for your current work session. This helps you track progress and organize complex tasks.\n\nOnly use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.\n\n## When to Use This Tool\n\nUse this tool in these scenarios:\n\n1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n3. User explicitly requests todo list - When the user directly asks you to use the todo list\n4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n5. The plan may need future revisions or updates based on results from the first few steps\n\n## How to Use This Tool\n\n1. When you start working on a task - Mark it as in_progress BEFORE beginning work.\n2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.\n3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.\n4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.\n\n## When NOT to Use This Tool\n\nIt is important to skip using this tool when:\n1. There is only a single, straightforward task\n2. The task is trivial and tracking it provides no benefit\n3. The task can be completed in less than 3 trivial steps\n4. The task is purely conversational or informational\n\n## Task States and Management\n\n1. **Task States**: Use these states to track progress:\n - pending: Task not yet started\n - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)\n - completed: Task finished successfully\n\n2. **Task Management**:\n - Update task status in real-time as you work\n - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n - Complete current tasks before starting new ones\n - Remove tasks that are no longer relevant from the list entirely\n - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.\n - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress.\n\n3. **Task Completion Requirements**:\n - ONLY mark a task as completed when you have FULLY accomplished it\n - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n - When blocked, create a new task describing what needs to be resolved\n - Never mark a task as completed if:\n - There are unresolved issues or errors\n - Work is partial or incomplete\n - You encountered blockers that prevent completion\n - You couldn't find necessary resources or dependencies\n - Quality standards haven't been met\n\n4. **Task Breakdown**:\n - Create specific, actionable items\n - Break complex tasks into smaller, manageable steps\n - Use clear, descriptive task names\n\nBeing proactive with task management ensures you complete all requirements successfully\nRemember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all.\n\n## When You Finish\n\n`write_todos` tracks your work; it does not deliver the answer. Whatever the user asked for \u2014 computations, summaries, comparisons, data \u2014 must appear as text content in a message after your final `write_todos` call. Marking the last todo complete is not itself an answer to the user.", - "name": "write_todos", - "parameters": { - "properties": { - "todos": { - "items": { - "description": "A single todo item with content and status.", - "properties": { - "content": { - "type": "string" - }, - "status": { - "enum": [ - "pending", - "in_progress", - "completed" - ], - "type": "string" - } - }, - "required": [ - "content", - "status" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "todos" - ], - "type": "object" - } - }, - "type": "function" - }, { "function": { "description": "Lists all files in a directory.\n\nThis is useful for exploring the filesystem and finding the right file to read or edit.\nYou should almost ALWAYS use this tool before using the read_file or edit_file tools.", diff --git a/libs/deepagents/tests/unit_tests/test_end_to_end.py b/libs/deepagents/tests/unit_tests/test_end_to_end.py index e713e63baab..879b0df135a 100644 --- a/libs/deepagents/tests/unit_tests/test_end_to_end.py +++ b/libs/deepagents/tests/unit_tests/test_end_to_end.py @@ -133,11 +133,11 @@ def test_deep_agent_with_fake_llm_basic(self) -> None: messages=iter( [ AIMessage( - content="I'll use the sample_tool to process your request.", + content="I'll list the files to process your request.", tool_calls=[ { - "name": "write_todos", - "args": {"todos": []}, + "name": "ls", + "args": {}, "id": "call_1", "type": "tool_call", } diff --git a/libs/deepagents/tests/unit_tests/test_graph.py b/libs/deepagents/tests/unit_tests/test_graph.py index ce997b87e5b..52b8fea71dc 100644 --- a/libs/deepagents/tests/unit_tests/test_graph.py +++ b/libs/deepagents/tests/unit_tests/test_graph.py @@ -12,6 +12,7 @@ from unittest.mock import MagicMock, patch import pytest +from langchain.agents.middleware import TodoListMiddleware from langchain.agents.middleware.types import AgentMiddleware from langchain_core.language_models import BaseChatModel from langchain_core.messages import AIMessage, SystemMessage @@ -257,7 +258,6 @@ def test_create_deep_agent_passes_overrides_to_filesystem_and_task(self) -> None patch("deepagents.graph.resolve_model", return_value=fake_model), patch("deepagents.graph.FilesystemMiddleware", side_effect=[MagicMock(), MagicMock()]) as mock_fs, patch("deepagents.graph.SubAgentMiddleware", return_value=MagicMock()) as mock_subagents, - patch("deepagents.graph.TodoListMiddleware", return_value=MagicMock()), patch("deepagents.graph.PatchToolCallsMiddleware", return_value=MagicMock()), patch("deepagents.graph.create_summarization_middleware", return_value=MagicMock()), patch("deepagents.graph.create_agent", return_value=fake_agent), @@ -545,7 +545,6 @@ def _build_and_capture_system_prompt(self, profile_key: str, profile: HarnessPro patch("deepagents.graph.resolve_model", return_value=fake_model), patch("deepagents.graph.FilesystemMiddleware", side_effect=[MagicMock(), MagicMock()]), patch("deepagents.graph.SubAgentMiddleware", return_value=MagicMock()), - patch("deepagents.graph.TodoListMiddleware", return_value=MagicMock()), patch("deepagents.graph.PatchToolCallsMiddleware", return_value=MagicMock()), patch("deepagents.graph.create_summarization_middleware", return_value=MagicMock()), patch("deepagents.graph.create_agent", return_value=fake_agent) as mock_create, @@ -727,7 +726,6 @@ def test_exclusion_middleware_added_when_profile_has_excluded_tools(self) -> Non patch("deepagents.graph.resolve_model", return_value=fake_model), patch("deepagents.graph.FilesystemMiddleware", side_effect=[MagicMock(), MagicMock()]), patch("deepagents.graph.SubAgentMiddleware", return_value=MagicMock()), - patch("deepagents.graph.TodoListMiddleware", return_value=MagicMock()), patch("deepagents.graph.PatchToolCallsMiddleware", return_value=MagicMock()), patch("deepagents.graph.create_summarization_middleware", return_value=MagicMock()), patch("deepagents.graph.create_agent", return_value=fake_agent) as mock_create, @@ -759,7 +757,6 @@ def test_no_exclusion_middleware_when_no_excluded_tools(self) -> None: patch("deepagents.graph.resolve_model", return_value=fake_model), patch("deepagents.graph.FilesystemMiddleware", side_effect=[MagicMock(), MagicMock()]), patch("deepagents.graph.SubAgentMiddleware", return_value=MagicMock()), - patch("deepagents.graph.TodoListMiddleware", return_value=MagicMock()), patch("deepagents.graph.PatchToolCallsMiddleware", return_value=MagicMock()), patch("deepagents.graph.create_summarization_middleware", return_value=MagicMock()), patch("deepagents.graph.create_agent", return_value=fake_agent) as mock_create, @@ -792,7 +789,6 @@ def test_user_tools_pass_through_to_middleware_for_exclusion(self) -> None: patch("deepagents.graph.resolve_model", return_value=fake_model), patch("deepagents.graph.FilesystemMiddleware", side_effect=[MagicMock(), MagicMock()]), patch("deepagents.graph.SubAgentMiddleware", return_value=MagicMock()), - patch("deepagents.graph.TodoListMiddleware", return_value=MagicMock()), patch("deepagents.graph.PatchToolCallsMiddleware", return_value=MagicMock()), patch("deepagents.graph.create_summarization_middleware", return_value=MagicMock()), patch("deepagents.graph.create_agent", return_value=fake_agent) as mock_create, @@ -1637,14 +1633,12 @@ def test_class_entry_unknown_class_raises_coverage_error(self) -> None: _HARNESS_PROFILES.clear() _HARNESS_PROFILES.update(original) - def test_entry_matching_only_gp_subagent_stack_is_accepted(self) -> None: - """An entry matching only the GP subagent stack (not the main stack) is accepted. + def test_excluding_non_default_todo_middleware_raises_coverage_error(self) -> None: + """Excluding `TodoListMiddleware` now raises, since it is no longer a default. - Coverage is aggregated across all stacks the profile applies to, so a - profile-level exclusion only has to match somewhere — not in every - stack. `TodoListMiddleware` is added unconditionally to the GP - subagent stack; excluding it should work even though the main agent - also has one (both count as matches). + Todos are opt-in: `TodoListMiddleware` is not added to any default stack, + so a profile excluding it matches nothing across the main and GP subagent + stacks and trips the coverage guard — a typo/stale-profile signal. """ original = dict(_HARNESS_PROFILES) try: @@ -1653,17 +1647,11 @@ def test_entry_matching_only_gp_subagent_stack_is_accepted(self) -> None: HarnessProfile(excluded_middleware=frozenset({"TodoListMiddleware"})), ) fake_model = GenericFakeChatModel(messages=iter([AIMessage(content="ok")])) - fake_agent = MagicMock() - fake_agent.with_config.return_value = "compiled-agent" - with ( patch("deepagents.graph.resolve_model", return_value=fake_model), - patch("deepagents.graph.create_agent", return_value=fake_agent) as mock_create, + pytest.raises(ValueError, match="matched no middleware"), ): create_deep_agent(model="strexcprov:some-model") - - mw_stack = mock_create.call_args.kwargs["middleware"] - assert not any(type(m).__name__ == "TodoListMiddleware" for m in mw_stack) finally: _HARNESS_PROFILES.clear() _HARNESS_PROFILES.update(original) @@ -2649,6 +2637,79 @@ def name(self) -> str: gp_spec = next(s for s in sub_mw._subagents if s.get("name") == self._GP_NAME) assert not any(m is custom for m in gp_spec["middleware"]) + # ── TodoListMiddleware is opt-in (no longer a default) ───────────────────── + + def test_default_has_no_todos_in_main_or_gp(self) -> None: + """With no opt-in, neither the main agent nor the GP subagent has todos.""" + main_stack, sub_mw = self._setup([], enable_gp=True) + assert not any(isinstance(m, TodoListMiddleware) for m in main_stack) + gp_spec = next(s for s in sub_mw._subagents if s.get("name") == self._GP_NAME) + assert not any(isinstance(m, TodoListMiddleware) for m in gp_spec["middleware"]) + + def test_main_opt_in_todos_mirrors_to_gp(self) -> None: + """A caller-supplied TodoListMiddleware lands on the main agent and the GP subagent.""" + custom = TodoListMiddleware() + main_stack, sub_mw = self._setup([custom], enable_gp=True) + main_todos = [m for m in main_stack if isinstance(m, TodoListMiddleware)] + assert len(main_todos) == 1 + gp_spec = next(s for s in sub_mw._subagents if s.get("name") == self._GP_NAME) + gp_todos = [m for m in gp_spec["middleware"] if isinstance(m, TodoListMiddleware)] + assert len(gp_todos) == 1 + # Mirrored by reference so any caller configuration carries over. + assert gp_todos[0] is custom + + def test_declarative_subagent_todos_opt_in(self) -> None: + """A declarative subagent gets todos when its own spec includes the middleware.""" + subagent: SubAgent = { + "name": "helper", + "description": "A helper subagent", + "system_prompt": "You are a helper.", + "middleware": [TodoListMiddleware()], + } + _, sub_mw = self._setup([], subagents=[subagent]) + helper_spec = next(s for s in sub_mw._subagents if s.get("name") == "helper") + assert len([m for m in helper_spec["middleware"] if isinstance(m, TodoListMiddleware)]) == 1 + + def test_declarative_subagent_does_not_inherit_main_opt_in(self) -> None: + """Main-agent opt-in mirrors to the GP subagent only, not to declarative subagents.""" + subagent: SubAgent = { + "name": "helper", + "description": "A helper subagent", + "system_prompt": "You are a helper.", + } + _, sub_mw = self._setup([TodoListMiddleware()], subagents=[subagent]) + helper_spec = next(s for s in sub_mw._subagents if s.get("name") == "helper") + assert not any(isinstance(m, TodoListMiddleware) for m in helper_spec["middleware"]) + + def test_profile_extra_middleware_todos_on_main_and_gp(self) -> None: + """A profile that supplies todos via `extra_middleware` gets it on both stacks. + + This is the mechanism the GLM-5.2 and Codex profiles rely on to keep + `write_todos` after the SDK default was removed. + """ + original = dict(_HARNESS_PROFILES) + try: + register_harness_profile( + "todoprof", + HarnessProfile(extra_middleware=lambda: [TodoListMiddleware()]), + ) + fake_model = GenericFakeChatModel(messages=iter([AIMessage(content="ok")])) + fake_agent = MagicMock() + fake_agent.with_config.return_value = "compiled-agent" + with ( + patch("deepagents.graph.resolve_model", return_value=fake_model), + patch("deepagents.graph.create_agent", return_value=fake_agent) as mock_create, + ): + create_deep_agent(model="todoprof:some-model") + main_stack = mock_create.call_args.kwargs["middleware"] + assert len([m for m in main_stack if isinstance(m, TodoListMiddleware)]) == 1 + sub_mw = next(m for m in main_stack if isinstance(m, SubAgentMiddleware)) + gp_spec = next(s for s in sub_mw._subagents if s.get("name") == self._GP_NAME) + assert len([m for m in gp_spec["middleware"] if isinstance(m, TodoListMiddleware)]) == 1 + finally: + _HARNESS_PROFILES.clear() + _HARNESS_PROFILES.update(original) + def test_gp_profile_exclusion_wins_over_inherited_override(self) -> None: """Profile exclusion on a GP default slot wins even when the main agent supplies a replacement.""" custom = SummarizationMiddleware( diff --git a/libs/deepagents/tests/utils.py b/libs/deepagents/tests/utils.py index fa0c14c2757..c6d6f5bb94c 100644 --- a/libs/deepagents/tests/utils.py +++ b/libs/deepagents/tests/utils.py @@ -8,9 +8,7 @@ def assert_all_deepagent_qualities(agent): - assert "todos" in agent.stream_channels assert "files" in agent.stream_channels - assert "write_todos" in agent.nodes["tools"].bound._tools_by_name assert "ls" in agent.nodes["tools"].bound._tools_by_name assert "read_file" in agent.nodes["tools"].bound._tools_by_name assert "write_file" in agent.nodes["tools"].bound._tools_by_name From 4d94252f1c1c4448f68b417edca808c2e08b5b5a Mon Sep 17 00:00:00 2001 From: Shrikar Seshadri Date: Tue, 21 Jul 2026 19:35:21 -0700 Subject: [PATCH 2/8] test(deepagents,quickjs): regenerate smoke snapshots without write_todos Regenerate the SDK smoke snapshot added on main (`system_prompt_with_read_file_only`) and the quickjs prompt snapshots so they no longer contain the `write_todos` tool now that the todo list is opt-in. --- .../system_prompt_with_read_file_only.md | 19 ------------------- ...s_system_prompt_mixed_foreign_functions.md | 19 ------------------- ...tem_prompt_mixed_foreign_functions_call.md | 19 ------------------- ...tem_prompt_mixed_foreign_functions_turn.md | 19 ------------------- .../quickjs_system_prompt_no_tools.md | 19 ------------------- .../quickjs_system_prompt_no_tools_call.md | 19 ------------------- .../quickjs_system_prompt_no_tools_turn.md | 19 ------------------- 7 files changed, 133 deletions(-) diff --git a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_read_file_only.md b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_read_file_only.md index d5e5aad9878..2dc16d116df 100644 --- a/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_read_file_only.md +++ b/libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_read_file_only.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions.md b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions.md index 7012257bc0a..dec452d1a72 100644 --- a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions.md +++ b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions_call.md b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions_call.md index c2fc2e249f4..8b01fd8e1cb 100644 --- a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions_call.md +++ b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions_call.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions_turn.md b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions_turn.md index 6392a881803..92a67cd1856 100644 --- a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions_turn.md +++ b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_mixed_foreign_functions_turn.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools.md b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools.md index f0b48ac0809..45e25abd09c 100644 --- a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools.md +++ b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools_call.md b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools_call.md index 54b553ba547..49594d9d267 100644 --- a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools_call.md +++ b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools_call.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes diff --git a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools_turn.md b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools_turn.md index 2a3ea7d9d26..5ba7e288e33 100644 --- a/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools_turn.md +++ b/libs/partners/quickjs/tests/unit_tests/smoke_tests/snapshots/quickjs_system_prompt_no_tools_turn.md @@ -42,25 +42,6 @@ Keep working until the task is fully complete. Don't stop partway and explain wh For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next. -## `write_todos` - -You have access to the `write_todos` tool to help you manage and plan complex objectives. -Use this tool for complex objectives to ensure that you are tracking each necessary step. -This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps. - -It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed. -For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool. -Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests. - -## Important To-Do List Usage Notes to Remember - -- The `write_todos` tool should never be called multiple times in parallel. -- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant. - -## Finishing a task - -When you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done. - ## Following Conventions - Read files before editing — understand existing content before making changes From ecdccdf6ae7f0d2e9f7571593cfd6346a50ee337 Mon Sep 17 00:00:00 2001 From: Shrikar Seshadri Date: Tue, 21 Jul 2026 19:41:16 -0700 Subject: [PATCH 3/8] build(quickjs): sync uv.lock with pyproject after merge --- libs/partners/quickjs/uv.lock | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/libs/partners/quickjs/uv.lock b/libs/partners/quickjs/uv.lock index 2c4857926b6..397be620462 100644 --- a/libs/partners/quickjs/uv.lock +++ b/libs/partners/quickjs/uv.lock @@ -488,7 +488,7 @@ requires-dist = [ { name = "langchain-google-genai", specifier = ">=4.2.7,<5.0.0" }, { name = "langchain-quickjs", marker = "extra == 'quickjs'", specifier = ">=0.3.3" }, { name = "langsmith", specifier = ">=0.9.3" }, - { name = "pillow", marker = "extra == 'video'", specifier = ">=10.0.0,<13.0.0" }, + { name = "pillow", marker = "extra == 'video'", specifier = ">=12.3.0,<13.0.0" }, { name = "wcmatch", specifier = ">=10.1" }, ] provides-extras = ["aws", "quickjs", "video"] @@ -499,7 +499,7 @@ test = [ { name = "build" }, { name = "langchain-openai" }, { name = "langchain-tests", specifier = ">=1.1.9" }, - { name = "pillow", specifier = ">=10.0.0,<13.0.0" }, + { name = "pillow", specifier = ">=12.3.0,<13.0.0" }, { name = "pytest" }, { name = "pytest-asyncio", specifier = ">=1.4.0" }, { name = "pytest-benchmark" }, From 48685bab8288123c9d1412df7fb79ffca6ed5d4b Mon Sep 17 00:00:00 2001 From: Shrikar Seshadri Date: Tue, 21 Jul 2026 19:58:39 -0700 Subject: [PATCH 4/8] docs(deepagents): clarify GP subagent keeps its own todo list The mirror only shares the `write_todos` tool with the general-purpose subagent; the `todos` state is isolated per subagent, so each keeps its own list. --- libs/deepagents/deepagents/graph.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/libs/deepagents/deepagents/graph.py b/libs/deepagents/deepagents/graph.py index 1beaf50f698..c379ef42ae3 100644 --- a/libs/deepagents/deepagents/graph.py +++ b/libs/deepagents/deepagents/graph.py @@ -845,8 +845,10 @@ class MyState(DeepAgentState): # Inherit middleware that overrides a default GP slot (including excluded # ones) without carrying over middleware that's specific to the main agent. # TodoListMiddleware is a special case: it is no longer a GP default, but a - # caller-supplied instance on the main agent is mirrored here so the todo - # list is shared between the main agent and the general-purpose subagent. + # caller-supplied instance on the main agent is mirrored here so the + # general-purpose subagent also gets the `write_todos` tool. The todos + # state stays isolated per subagent (see `_EXCLUDED_STATE_KEYS`); each + # agent keeps its own list. _gp_inheritable = [m for m in (middleware or []) if m.name in _gp_original_name_to_index or isinstance(m, TodoListMiddleware)] gp_middleware = _apply_custom_middleware(gp_middleware, _gp_inheritable, core_names=_gp_core_names) gp_middleware = _apply_excluded_middleware( From b68bbf4950a3ae7b6b32b1b9610210af3364020b Mon Sep 17 00:00:00 2001 From: Shrikar Seshadri Date: Wed, 22 Jul 2026 13:50:37 -0700 Subject: [PATCH 5/8] refactor(sdk): treat todo middleware like any other on GP subagent --- libs/deepagents/deepagents/graph.py | 28 ++++++++++--------- .../profiles/harness/harness_profiles.py | 4 +-- .../deepagents/tests/unit_tests/test_graph.py | 25 ++++++++++++----- 3 files changed, 35 insertions(+), 22 deletions(-) diff --git a/libs/deepagents/deepagents/graph.py b/libs/deepagents/deepagents/graph.py index c379ef42ae3..1d701864c4c 100644 --- a/libs/deepagents/deepagents/graph.py +++ b/libs/deepagents/deepagents/graph.py @@ -10,7 +10,7 @@ from typing import Annotated, Any, Required, TypedDict, cast from langchain.agents import AgentState, create_agent -from langchain.agents.middleware import HumanInTheLoopMiddleware, InterruptOnConfig, TodoListMiddleware +from langchain.agents.middleware import HumanInTheLoopMiddleware, InterruptOnConfig from langchain.agents.middleware.types import ( AgentMiddleware, InputAgentState, @@ -364,8 +364,10 @@ def create_deep_agent( # noqa: C901, PLR0912, PLR0915 # Complex graph assembly Todo-list support (the `write_todos` tool) is opt-in: pass [`TodoListMiddleware`][langchain.agents.middleware.TodoListMiddleware] - via `middleware=` to enable it. When enabled on the main agent it is also - mirrored onto the automatic general-purpose subagent. + via `middleware=` to enable it on the main agent. It is not propagated to + the automatic general-purpose subagent; to give that subagent todos, + override it with a subagent named `general-purpose` whose `middleware` + list includes `TodoListMiddleware`. The `execute` tool allows running shell commands if the backend implements [`SandboxBackendProtocol`][deepagents.backends.protocol.SandboxBackendProtocol]. @@ -434,8 +436,10 @@ def create_deep_agent( # noqa: C901, PLR0912, PLR0915 # Complex graph assembly Todo-list support is opt-in here: passing a [`TodoListMiddleware`][langchain.agents.middleware.TodoListMiddleware] - instance enables the `write_todos` tool on the main agent and - mirrors it onto the automatic general-purpose subagent. + instance enables the `write_todos` tool on the main agent only. It + is not propagated to the automatic general-purpose subagent; to give + that subagent todos, override it with a subagent named + `general-purpose` whose `middleware` list includes it. The full ordering is: @@ -828,7 +832,7 @@ class MyState(DeepAgentState): gp_middleware.append(SkillsMiddleware(backend=backend, sources=skills)) # Core names captured before the tail so an inherited main-agent - # middleware (e.g. an opt-in TodoListMiddleware) splices in after the + # middleware (one overriding a default GP slot) splices in after the # real tools, ahead of the profile/prompt-caching tail. _gp_core_names = {m.name for m in gp_middleware} # Add harness-profile middleware, if any @@ -843,13 +847,11 @@ class MyState(DeepAgentState): matched_names=_main_matched_names, ) # Inherit middleware that overrides a default GP slot (including excluded - # ones) without carrying over middleware that's specific to the main agent. - # TodoListMiddleware is a special case: it is no longer a GP default, but a - # caller-supplied instance on the main agent is mirrored here so the - # general-purpose subagent also gets the `write_todos` tool. The todos - # state stays isolated per subagent (see `_EXCLUDED_STATE_KEYS`); each - # agent keeps its own list. - _gp_inheritable = [m for m in (middleware or []) if m.name in _gp_original_name_to_index or isinstance(m, TodoListMiddleware)] + # ones) without carrying over middleware that's specific to the main + # agent. Main-agent-only middleware (e.g. an opt-in TodoListMiddleware) + # is not mirrored here; to give the general-purpose subagent that + # middleware, override it with a subagent named `general-purpose`. + _gp_inheritable = [m for m in (middleware or []) if m.name in _gp_original_name_to_index] gp_middleware = _apply_custom_middleware(gp_middleware, _gp_inheritable, core_names=_gp_core_names) gp_middleware = _apply_excluded_middleware( gp_middleware, diff --git a/libs/deepagents/deepagents/profiles/harness/harness_profiles.py b/libs/deepagents/deepagents/profiles/harness/harness_profiles.py index 673e81c8509..453850893b6 100644 --- a/libs/deepagents/deepagents/profiles/harness/harness_profiles.py +++ b/libs/deepagents/deepagents/profiles/harness/harness_profiles.py @@ -632,8 +632,8 @@ class HarnessProfile: Entries may be a middleware *class* (matched by exact type, not subclass — consistent with `extra_middleware` slot merging) or a *string* matching `AgentMiddleware.name` exactly. `.name` defaults to the class's - `__name__` but is overridable, so `{TodoListMiddleware}` (class form) and - `{"TodoListMiddleware"}` (name form) behave identically for stock + `__name__` but is overridable, so `{FilesystemMiddleware}` (class form) and + `{"FilesystemMiddleware"}` (name form) behave identically for stock middleware. Prefer class form when the class is importable: typos surface at import diff --git a/libs/deepagents/tests/unit_tests/test_graph.py b/libs/deepagents/tests/unit_tests/test_graph.py index 2ef4c5fe724..23df0442bc7 100644 --- a/libs/deepagents/tests/unit_tests/test_graph.py +++ b/libs/deepagents/tests/unit_tests/test_graph.py @@ -2648,17 +2648,28 @@ def test_default_has_no_todos_in_main_or_gp(self) -> None: gp_spec = next(s for s in sub_mw._subagents if s.get("name") == self._GP_NAME) assert not any(isinstance(m, TodoListMiddleware) for m in gp_spec["middleware"]) - def test_main_opt_in_todos_mirrors_to_gp(self) -> None: - """A caller-supplied TodoListMiddleware lands on the main agent and the GP subagent.""" + def test_main_opt_in_todos_not_mirrored_to_gp(self) -> None: + """A caller-supplied TodoListMiddleware stays on the main agent only. + + It is treated like any other main-agent-only middleware: because it is + not a default GP slot, it is not propagated to the general-purpose + subagent. + """ custom = TodoListMiddleware() main_stack, sub_mw = self._setup([custom], enable_gp=True) main_todos = [m for m in main_stack if isinstance(m, TodoListMiddleware)] assert len(main_todos) == 1 gp_spec = next(s for s in sub_mw._subagents if s.get("name") == self._GP_NAME) - gp_todos = [m for m in gp_spec["middleware"] if isinstance(m, TodoListMiddleware)] - assert len(gp_todos) == 1 - # Mirrored by reference so any caller configuration carries over. - assert gp_todos[0] is custom + assert not any(isinstance(m, TodoListMiddleware) for m in gp_spec["middleware"]) + + def test_gp_override_can_opt_in_todos(self) -> None: + """Overriding the GP subagent by name lets its own middleware add todos.""" + from deepagents.middleware.subagents import GENERAL_PURPOSE_SUBAGENT # noqa: PLC0415 + + gp_override: SubAgent = {**GENERAL_PURPOSE_SUBAGENT, "middleware": [TodoListMiddleware()]} + _, sub_mw = self._setup([], subagents=[gp_override]) + gp_spec = next(s for s in sub_mw._subagents if s.get("name") == self._GP_NAME) + assert len([m for m in gp_spec["middleware"] if isinstance(m, TodoListMiddleware)]) == 1 def test_declarative_subagent_todos_opt_in(self) -> None: """A declarative subagent gets todos when its own spec includes the middleware.""" @@ -2673,7 +2684,7 @@ def test_declarative_subagent_todos_opt_in(self) -> None: assert len([m for m in helper_spec["middleware"] if isinstance(m, TodoListMiddleware)]) == 1 def test_declarative_subagent_does_not_inherit_main_opt_in(self) -> None: - """Main-agent opt-in mirrors to the GP subagent only, not to declarative subagents.""" + """A main-agent todos opt-in is not inherited by a declarative subagent.""" subagent: SubAgent = { "name": "helper", "description": "A helper subagent", From d0b362ef9f9c3684a70447fb26e1a387a8dca314 Mon Sep 17 00:00:00 2001 From: Shrikar Seshadri Date: Wed, 22 Jul 2026 16:19:58 -0700 Subject: [PATCH 6/8] refactor(sdk): drop vestigial _gp_core_names from GP subagent --- libs/deepagents/deepagents/graph.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/libs/deepagents/deepagents/graph.py b/libs/deepagents/deepagents/graph.py index 1d701864c4c..b6f10810f9b 100644 --- a/libs/deepagents/deepagents/graph.py +++ b/libs/deepagents/deepagents/graph.py @@ -831,10 +831,6 @@ class MyState(DeepAgentState): if skills is not None: gp_middleware.append(SkillsMiddleware(backend=backend, sources=skills)) - # Core names captured before the tail so an inherited main-agent - # middleware (one overriding a default GP slot) splices in after the - # real tools, ahead of the profile/prompt-caching tail. - _gp_core_names = {m.name for m in gp_middleware} # Add harness-profile middleware, if any gp_middleware.extend(_profile.materialize_extra_middleware()) @@ -852,7 +848,7 @@ class MyState(DeepAgentState): # is not mirrored here; to give the general-purpose subagent that # middleware, override it with a subagent named `general-purpose`. _gp_inheritable = [m for m in (middleware or []) if m.name in _gp_original_name_to_index] - gp_middleware = _apply_custom_middleware(gp_middleware, _gp_inheritable, core_names=_gp_core_names) + gp_middleware = _apply_custom_middleware(gp_middleware, _gp_inheritable) gp_middleware = _apply_excluded_middleware( gp_middleware, _profile, From 0732b3585bb4d58c405b9c22904150bf272a658e Mon Sep 17 00:00:00 2001 From: Shrikar Seshadri <146694785+davibinboi@users.noreply.github.com> Date: Thu, 23 Jul 2026 07:10:05 -0700 Subject: [PATCH 7/8] feat(code)!: remove default todos, matching SDK opt-in (#4992) --- libs/code/deepagents_code/_env_vars.py | 6 +- libs/code/deepagents_code/agent.py | 101 +----------- libs/code/deepagents_code/system_prompt.md | 2 - .../system_prompt_interactive_local.md | 18 --- libs/code/tests/unit_tests/test_agent.py | 144 +++--------------- libs/code/tests/unit_tests/test_end_to_end.py | 4 +- .../tests/unit_tests/test_tool_catalog.py | 22 +-- 7 files changed, 28 insertions(+), 269 deletions(-) diff --git a/libs/code/deepagents_code/_env_vars.py b/libs/code/deepagents_code/_env_vars.py index 784351e4269..edfc82f40af 100644 --- a/libs/code/deepagents_code/_env_vars.py +++ b/libs/code/deepagents_code/_env_vars.py @@ -159,10 +159,8 @@ """Opt into experimental, unstable dcode behavior. Off by default; parsed by `is_env_truthy` (see there for the accepted truthy -values). Currently gates dropping the SDK's `TodoListMiddleware` (and its -`write_todos` tool) from the agent and its subagents, along with the matching -todo-list prompt guidance. Behavior behind this flag may change or be removed -without notice. +values). Currently gates the beta classifier-backed Auto approval mode. +Behavior behind this flag may change or be removed without notice. """ EXTERNAL_EVENT_SOCKET = "DEEPAGENTS_CODE_EXTERNAL_EVENT_SOCKET" diff --git a/libs/code/deepagents_code/agent.py b/libs/code/deepagents_code/agent.py index 307670db2ea..d6e6f5405b5 100644 --- a/libs/code/deepagents_code/agent.py +++ b/libs/code/deepagents_code/agent.py @@ -48,7 +48,6 @@ from langchain.agents.middleware import ( HumanInTheLoopMiddleware, InterruptOnConfig, - TodoListMiddleware, ) from langchain.agents.middleware.types import AgentMiddleware from langchain.tools import ( @@ -142,37 +141,6 @@ """When `True`, `compact_conversation` requires HITL approval like other gated tools.""" -class _NoTodoListMiddleware(AgentMiddleware): - """No-op stand-in that drops the SDK's `TodoListMiddleware` by name. - - `create_deep_agent` always injects `TodoListMiddleware` and exposes no - per-call parameter to disable it (only a globally registered - `HarnessProfile.excluded_middleware` can strip it, which dcode does not use - here). Its `_apply_custom_middleware` merge replaces a default middleware in - place when a caller-supplied middleware shares its `.name`, so threading - this tool-less stand-in into the agent and subagent middleware lists removes - the real middleware — and its `write_todos` tool — without touching the SDK. - - Deriving `name` from `TodoListMiddleware.__name__` makes a *rename* or - removal of the SDK class fail loudly (`ImportError`) at the top-of-module - import. It does not, on its own, guard a `.name` *override* on an unrenamed - class: the merge keys on the instance `.name`, not `__name__`, so such an - override would slip past the import and silently turn this into a no-op. - That case is caught two ways — `_todo_list_middleware_override` re-checks the - match at build time and raises, and `test_agent.py` guards it in CI. Gated - behind `DEEPAGENTS_CODE_EXPERIMENTAL`; see `_todo_list_middleware_override`. - """ - - name: str = TodoListMiddleware.__name__ - tools: Sequence[BaseTool] = () - """No tools — replacing the real `TodoListMiddleware` drops its `write_todos`. - - Declared explicitly (mirroring the base's `transformers = ()` default) so a - bare instance is self-contained rather than relying on the SDK's - `getattr(mw, "tools", [])` fallback. - """ - - def _get_harness_tool_descriptions( model: str | BaseChatModel, ) -> dict[str, str]: @@ -262,41 +230,6 @@ def _inject_fs_tools_into_subagents( ) -def _todo_list_middleware_override() -> list[AgentMiddleware]: - """Return the middleware needed to strip `TodoListMiddleware`, if enabled. - - Returns a single-element list with `_NoTodoListMiddleware` when the - experimental flag is set, else an empty list. Callers splice the result - into the middleware list they pass to `create_deep_agent` so the SDK's - name-based merge drops the real `TodoListMiddleware`. - - Raises: - RuntimeError: If the stand-in's `.name` no longer matches the SDK - middleware's instance `.name`. The merge replaces by name, so a - mismatch would silently *append* the tool-less stand-in instead of - replacing the real middleware, leaving `write_todos` bound. Failing - fast here converts that silent no-op into a loud, actionable error - (only ever runs when the flag is on). - """ - if not is_env_truthy(EXPERIMENTAL): - return [] - stand_in = _NoTodoListMiddleware() - sdk_name = TodoListMiddleware().name - if stand_in.name != sdk_name: - msg = ( - f"{EXPERIMENTAL} is set but the TodoListMiddleware override would be " - f"a silent no-op: stand-in name {stand_in.name!r} no longer matches " - f"the SDK middleware's instance name {sdk_name!r}. The SDK likely " - f"overrode TodoListMiddleware.name; update _NoTodoListMiddleware." - ) - raise RuntimeError(msg) - logger.info( - "%s set: dropping TodoListMiddleware / write_todos from this stack", - EXPERIMENTAL, - ) - return [stand_in] - - def _rubric_grader_read_file_prefix(backend: CompositeBackend) -> str: """Return the offloaded-results directory the rubric grader is allowed to read. @@ -534,7 +467,7 @@ def _resolve_ptc_option( """Resolve the configured PTC allowlist to a concrete list of tool names. Names are *not* validated against `tools`. The Deep Agents SDK injects the - filesystem, `task`, `write_todos`, and `execute` tools via middleware in + filesystem, `task`, and `execute` tools via middleware in `create_deep_agent` — *after* this point — so they are absent from `tools` here, and the SDK exposes no importable list of them. `CodeInterpreterMiddleware` matches the resolved names against the live runtime registry and silently @@ -1056,8 +989,7 @@ def get_system_prompt( Loads the base system prompt template from `system_prompt.md` and interpolates dynamic sections (model identity, working directory, - skills path, execution mode, and todo-list guidance for - interactive vs headless). + skills path, and execution mode for interactive vs headless). Args: assistant_id: The agent identifier for path references @@ -1085,9 +1017,6 @@ def get_system_prompt( """ prompt_dir = Path(__file__).parent template = (prompt_dir / "system_prompt.md").read_text() - todo_list_section = "" - if not is_env_truthy(EXPERIMENTAL): - todo_list_section = (prompt_dir / "todo_list_prompt.md").read_text().rstrip() skills_path = f"~/.deepagents/{assistant_id}/skills" @@ -1103,15 +1032,6 @@ def get_system_prompt( "- If the request is ambiguous, ask questions before acting.\n" "- If asked how to approach something, explain first, then act." ) - todo_guidance = ( - "6. When first creating a todo list for a task, ALWAYS ask the user if " - "the plan looks good before starting work\n" - ' - Create the todos, then ask: "Does this plan ' - 'look good?" or similar\n' - " - Wait for the user's response before marking the first todo as " - "in_progress\n" - "7. Update todo status promptly as you complete each item" - ) else: mode_description = ( "non-interactive (headless) mode — there is no human operator " @@ -1134,15 +1054,6 @@ def get_system_prompt( "`yes |` or `--no-input`/`--non-interactive` flags where " "available. Never run commands that block waiting for stdin." ) - todo_guidance = ( - "6. There is no human operator in this mode — do NOT ask the user to " - "approve your plan or wait for a reply.\n" - " After you create todos for a multi-step task, mark the first item " - "`in_progress` immediately and start work.\n" - " If the plan needs adjustment, revise the todo list yourself; do " - "not block on human confirmation.\n" - "7. Update todo status promptly as you complete each item" - ) model_identity_section = build_model_identity_section( settings.model_name, @@ -1200,8 +1111,6 @@ def get_system_prompt( template.replace("{mode_description}", mode_description) .replace("{interactive_preamble}", interactive_preamble) .replace("{ambiguity_guidance}", ambiguity_guidance) - .replace("{todo_list_section}", todo_list_section) - .replace("{todo_guidance}", todo_guidance) .replace("{model_identity_section}", model_identity_section) .replace("{working_dir_section}", working_dir_section) .replace("{skills_path}", skills_path) @@ -2057,9 +1966,6 @@ def _subagent_cli_middleware( has_explicit_model: bool, ) -> list[AgentMiddleware[Any, Any]]: middleware: list[AgentMiddleware[Any, Any]] = [] - # Experimental: mirror the main agent and drop TodoListMiddleware / - # write_todos from subagent stacks too. No-op unless the flag is set. - middleware.extend(_todo_list_middleware_override()) if resolved_interrupt_on is not None: middleware.append(AsyncApprovalHITLMiddleware(resolved_interrupt_on)) if not has_explicit_model: @@ -2137,9 +2043,6 @@ def _subagent_cli_middleware( # Build middleware stack based on enabled features agent_middleware: list[AgentMiddleware[Any, Any]] = [ ConfigurableModelMiddleware(), - # Experimental: drop the SDK's TodoListMiddleware / write_todos tool. - # No-op unless DEEPAGENTS_CODE_EXPERIMENTAL is truthy. - *_todo_list_middleware_override(), ] if not interactive: agent_middleware.append(_GlmTerminalStallRecovery()) diff --git a/libs/code/deepagents_code/system_prompt.md b/libs/code/deepagents_code/system_prompt.md index 21420a93313..eb5a341b45b 100644 --- a/libs/code/deepagents_code/system_prompt.md +++ b/libs/code/deepagents_code/system_prompt.md @@ -211,5 +211,3 @@ When you use the web_search tool: 6. If the search doesn't find what you need, explain what you found and ask clarifying questions The user only sees your text responses - not tool results. Always provide a complete, natural language answer after using web_search. - -{todo_list_section} diff --git a/libs/code/tests/unit_tests/smoke_tests/snapshots/system_prompt_interactive_local.md b/libs/code/tests/unit_tests/smoke_tests/snapshots/system_prompt_interactive_local.md index d33897ef5dc..479ce04b6ab 100644 --- a/libs/code/tests/unit_tests/smoke_tests/snapshots/system_prompt_interactive_local.md +++ b/libs/code/tests/unit_tests/smoke_tests/snapshots/system_prompt_interactive_local.md @@ -233,24 +233,6 @@ When you use the web_search tool: The user only sees your text responses - not tool results. Always provide a complete, natural language answer after using web_search. -### Todo List Management - -When using the write_todos tool: - -1. Use todos for any task with 2+ steps — they give the user visibility -2. Mark tasks `in_progress` before starting, `completed` immediately after -3. Don't batch completions — mark each item done as you finish it -4. If a task reveals sub-tasks, add them right away -5. For simple 1-step tasks, just do them directly -6. When first creating a todo list for a task, ALWAYS ask the user if the plan looks good before starting work - - Create the todos, then ask: "Does this plan look good?" or similar - - Wait for the user's response before marking the first todo as in_progress -7. Update todo status promptly as you complete each item - -The todo list is a planning tool - use it judiciously to avoid overwhelming the user with excessive task tracking. - - - ## Shell paths vs. virtual paths diff --git a/libs/code/tests/unit_tests/test_agent.py b/libs/code/tests/unit_tests/test_agent.py index b0b6156d899..ff96e21c36c 100644 --- a/libs/code/tests/unit_tests/test_agent.py +++ b/libs/code/tests/unit_tests/test_agent.py @@ -11,7 +11,6 @@ from unittest.mock import Mock, patch import pytest -from langchain.agents.middleware import TodoListMiddleware from langchain_core.language_models.fake_chat_models import GenericFakeChatModel from langchain_core.messages import AIMessage from langgraph.errors import GraphInterrupt @@ -1552,66 +1551,23 @@ def test_default_is_interactive(self) -> None: assert "interactive TUI" in prompt - def test_interactive_todo_section_asks_user_before_starting(self) -> None: - """Interactive mode should require plan approval before first in_progress.""" - mock_settings = Mock() - mock_settings.model_name = None - - with patch("deepagents_code.agent.settings", mock_settings): - prompt = get_system_prompt("test-agent", interactive=True) - - assert "Wait for the user's response before marking the first todo" in prompt - - def test_non_interactive_todo_section_does_not_wait_for_user(self) -> None: - """Headless mode must not contradict 'no human' guidance in todo rules.""" - mock_settings = Mock() - mock_settings.model_name = None - - with patch("deepagents_code.agent.settings", mock_settings): - prompt = get_system_prompt("test-agent", interactive=False) - - wait_for_user = "Wait for the user's response before marking the first todo" - assert wait_for_user not in prompt - assert "do NOT ask the user to approve your plan" in prompt - assert "mark the first item `in_progress` immediately" in prompt + def test_prompt_omits_todo_guidance(self) -> None: + """Todos are opt-in in the SDK, so dcode's prompt must not reference them. - def test_experimental_prompt_omits_todo_section( - self, monkeypatch: pytest.MonkeyPatch - ) -> None: - """Experimental mode must not reference its removed todo tool.""" - monkeypatch.setenv(EXPERIMENTAL, "1") - mock_settings = Mock() - mock_settings.model_name = None - - with patch("deepagents_code.agent.settings", mock_settings): - prompt = get_system_prompt("test-agent") - - assert "Todo List Management" not in prompt - assert "write_todos" not in prompt - # `{todo_guidance}` lives only inside the gated section, so dropping the - # section must not leave the placeholder unresolved. - assert "{todo_list_section}" not in prompt - assert "{todo_guidance}" not in prompt - - def test_default_prompt_resolves_todo_placeholders( - self, monkeypatch: pytest.MonkeyPatch - ) -> None: - """Default mode keeps the todo section with no unresolved placeholders. - - Guards the `.replace` ordering in `get_system_prompt`: `{todo_guidance}` - is nested inside the todo section, so the section must be substituted - before the guidance placeholder is filled. + Covers both modes and guards against leftover placeholders once the + `{todo_list_section}`/`{todo_guidance}` wiring is gone. """ - monkeypatch.delenv(EXPERIMENTAL, raising=False) mock_settings = Mock() mock_settings.model_name = None - with patch("deepagents_code.agent.settings", mock_settings): - prompt = get_system_prompt("test-agent") + for interactive in (True, False): + with patch("deepagents_code.agent.settings", mock_settings): + prompt = get_system_prompt("test-agent", interactive=interactive) - assert "Todo List Management" in prompt - assert "{todo_list_section}" not in prompt - assert "{todo_guidance}" not in prompt + assert "Todo List Management" not in prompt + assert "write_todos" not in prompt + assert "{todo_list_section}" not in prompt + assert "{todo_guidance}" not in prompt class TestGetSystemPromptCwdOSError: @@ -4445,14 +4401,13 @@ def test_async_subagents_are_not_restricted(self, tmp_path: Path) -> None: ] -class TestExperimentalTodoMiddlewareWiring: - """`DEEPAGENTS_CODE_EXPERIMENTAL` drops TodoListMiddleware from every stack. +class TestAutoModeSubagentHITLWiring: + """Auto-mode async HITL reaches every dcode subagent stack. - `collect_built_in_tools` (see `test_tool_catalog.py`) only inspects the main - agent's bound tools, so the subagent splice needs its own coverage: these - tests capture the `create_deep_agent` kwargs and assert the stand-in reaches - the main agent, custom subagents, and the general-purpose subagent that - dcode auto-adds. + These tests capture the `create_deep_agent` kwargs and assert that, in Auto + mode (gated behind `DEEPAGENTS_CODE_EXPERIMENTAL`), the async approval + middleware reaches both custom subagents and the general-purpose subagent + that dcode auto-adds. """ @staticmethod @@ -4536,71 +4491,6 @@ def _capture_create_deep_agent_kwargs( _, kwargs = mock_create.call_args return kwargs - @staticmethod - def _has_todo_standin(middleware: list[Any]) -> bool: - return any( - getattr(mw, "name", None) == TodoListMiddleware.__name__ - for mw in middleware - ) - - def test_standin_name_matches_sdk_middleware(self) -> None: - """The stand-in must impersonate the real middleware's `.name`. - - The name-based merge keys on the instance `.name`, so this guards a - hypothetical SDK `.name` override that `__name__`-derivation would miss. - """ - from deepagents_code.agent import _NoTodoListMiddleware - - assert _NoTodoListMiddleware().name == TodoListMiddleware().name - - def test_dropped_from_main_and_subagents_when_experimental( - self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch - ) -> None: - monkeypatch.setenv(EXPERIMENTAL, "1") - kwargs = self._capture_create_deep_agent_kwargs(tmp_path) - - assert self._has_todo_standin(kwargs["middleware"]) - - subagents_by_name = {sa["name"]: sa for sa in kwargs["subagents"]} - assert {"researcher", "general-purpose"} <= set(subagents_by_name) - for name, spec in subagents_by_name.items(): - assert self._has_todo_standin(spec.get("middleware", [])), ( - f"Expected TodoListMiddleware stand-in on subagent {name!r}" - ) - - def test_dropped_from_explicit_model_subagent_when_experimental( - self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch - ) -> None: - """The splice must survive the `has_explicit_model` branch. - - `_subagent_cli_middleware` extends the stand-in in *before* the - `if not has_explicit_model:` model-middleware check, so a subagent with - an explicit `model:` in frontmatter must still receive it. The other - wiring cases only exercise the `model: None` branch, so without this a - regression that moved the splice inside that `if` would pass unnoticed. - """ - monkeypatch.setenv(EXPERIMENTAL, "1") - kwargs = self._capture_create_deep_agent_kwargs( - tmp_path, subagent_model="fake-model" - ) - - subagents_by_name = {sa["name"]: sa for sa in kwargs["subagents"]} - researcher = subagents_by_name["researcher"] - # Guards the premise: an explicit model must reach the spec, else the - # subagent would take the `model: None` path and the test proves nothing. - assert researcher.get("model"), "explicit subagent model was not forwarded" - assert self._has_todo_standin(researcher.get("middleware", [])) - - def test_absent_from_all_stacks_by_default( - self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch - ) -> None: - monkeypatch.delenv(EXPERIMENTAL, raising=False) - kwargs = self._capture_create_deep_agent_kwargs(tmp_path) - - assert not self._has_todo_standin(kwargs["middleware"]) - for spec in kwargs["subagents"]: - assert not self._has_todo_standin(spec.get("middleware", [])) - async def test_async_hitl_covers_declarative_and_general_subagents_in_auto( self, tmp_path: Path, diff --git a/libs/code/tests/unit_tests/test_end_to_end.py b/libs/code/tests/unit_tests/test_end_to_end.py index cb38cfee0b5..e666118ec5c 100644 --- a/libs/code/tests/unit_tests/test_end_to_end.py +++ b/libs/code/tests/unit_tests/test_end_to_end.py @@ -133,8 +133,8 @@ def test_cli_agent_with_fake_llm_basic(self, tmp_path: Path) -> None: content="I'll help you with that.", tool_calls=[ { - "name": "write_todos", - "args": {"todos": []}, + "name": "ls", + "args": {}, "id": "call_1", "type": "tool_call", } diff --git a/libs/code/tests/unit_tests/test_tool_catalog.py b/libs/code/tests/unit_tests/test_tool_catalog.py index 9c757de596c..efaf23d993c 100644 --- a/libs/code/tests/unit_tests/test_tool_catalog.py +++ b/libs/code/tests/unit_tests/test_tool_catalog.py @@ -8,7 +8,6 @@ import pytest -from deepagents_code._env_vars import EXPERIMENTAL from deepagents_code.config import Settings from deepagents_code.mcp_tools import MCPServerInfo, MCPToolInfo from deepagents_code.tool_catalog import ( @@ -29,7 +28,6 @@ # Core tools the agent always binds, independent of optional integrations. _CORE_BUILT_IN = { - "write_todos", "ls", "read_file", "write_file", @@ -240,24 +238,14 @@ def test_raises_when_compiled_agent_not_inspectable(self) -> None: collect_built_in_tools() -class TestExperimentalTodoRemoval: - """`DEEPAGENTS_CODE_EXPERIMENTAL` drops the SDK `write_todos` tool.""" +class TestTodoToolNotBound: + """Todos are opt-in in the SDK, so dcode binds no `write_todos` by default.""" - def test_write_todos_bound_by_default( - self, monkeypatch: pytest.MonkeyPatch - ) -> None: - monkeypatch.delenv(EXPERIMENTAL, raising=False) - names = {tool.name for tool in collect_built_in_tools()} - assert "write_todos" in names - - def test_write_todos_removed_when_experimental( - self, monkeypatch: pytest.MonkeyPatch - ) -> None: - monkeypatch.setenv(EXPERIMENTAL, "1") + def test_write_todos_absent_by_default(self) -> None: names = {tool.name for tool in collect_built_in_tools()} assert "write_todos" not in names - # Only the todo tool is dropped; the rest of the core set stays bound. - assert names >= _CORE_BUILT_IN - {"write_todos"} + # The rest of the core set stays bound. + assert names >= _CORE_BUILT_IN class TestCollectToolsFromAgent: From 7a5feb824e13242b970f9162a3327bec19780cab Mon Sep 17 00:00:00 2001 From: Chester Curme Date: Thu, 23 Jul 2026 10:11:20 -0400 Subject: [PATCH 8/8] remove unnecessary context from comments and docstring --- libs/deepagents/deepagents/graph.py | 25 +++---------------------- 1 file changed, 3 insertions(+), 22 deletions(-) diff --git a/libs/deepagents/deepagents/graph.py b/libs/deepagents/deepagents/graph.py index b1a4ac0b4b8..6241234ebce 100644 --- a/libs/deepagents/deepagents/graph.py +++ b/libs/deepagents/deepagents/graph.py @@ -304,13 +304,6 @@ def create_deep_agent( # noqa: C901, PLR0912, PLR0915 # Complex graph assembly - `execute`: run shell commands - `task`: call subagents - Todo-list support (the `write_todos` tool) is opt-in: pass - [`TodoListMiddleware`][langchain.agents.middleware.TodoListMiddleware] - via `middleware=` to enable it on the main agent. It is not propagated to - the automatic general-purpose subagent; to give that subagent todos, - override it with a subagent named `general-purpose` whose `middleware` - list includes `TodoListMiddleware`. - The `execute` tool allows running shell commands if the backend implements [`SandboxBackendProtocol`][deepagents.backends.protocol.SandboxBackendProtocol]. For non-sandbox backends, the `execute` tool will return an error message. @@ -372,16 +365,7 @@ def create_deep_agent( # noqa: C901, PLR0912, PLR0915 # Complex graph assembly See [Prompt assembly](https://docs.langchain.com/oss/deepagents/customization#prompt-assembly) for the full case-by-case breakdown. middleware: Additional middleware to apply after the base stack - but before the tail middleware. - - Todo-list support is opt-in here: passing a - [`TodoListMiddleware`][langchain.agents.middleware.TodoListMiddleware] - instance enables the `write_todos` tool on the main agent only. It - is not propagated to the automatic general-purpose subagent; to give - that subagent todos, override it with a subagent named - `general-purpose` whose `middleware` list includes it. - - The full ordering is: + but before the tail middleware. The full ordering is: Base stack: @@ -794,11 +778,8 @@ class MyState(DeepAgentState): matched_classes=_main_matched_classes, matched_names=_main_matched_names, ) - # Inherit middleware that overrides a default GP slot (including excluded - # ones) without carrying over middleware that's specific to the main - # agent. Main-agent-only middleware (e.g. an opt-in TodoListMiddleware) - # is not mirrored here; to give the general-purpose subagent that - # middleware, override it with a subagent named `general-purpose`. + # Inherit only middleware that overrides a default GP slot (including excluded + # ones) without carrying over middleware that's specific to the main agent. _gp_inheritable = [m for m in (middleware or []) if m.name in _gp_original_name_to_index] gp_middleware = _apply_custom_middleware(gp_middleware, _gp_inheritable) gp_middleware = _apply_excluded_middleware(