Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 25 additions & 12 deletions libs/deepagents/deepagents/graph.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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]
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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())

Expand All @@ -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
Comment thread
davibinboi marked this conversation as resolved.
Resolved
# 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,
Expand Down Expand Up @@ -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]] = []
Comment thread
davibinboi marked this conversation as resolved.
Resolved
if skills is not None:
deepagent_middleware.append(SkillsMiddleware(backend=backend, sources=skills))
deepagent_middleware.append(
Expand Down
22 changes: 21 additions & 1 deletion libs/deepagents/deepagents/profiles/harness/_openai_codex.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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)
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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.",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading