langchain-ai/docs
1
0
Fork 0
mirror of https://github.com/langchain-ai/docs.git synced 2026-07-22 12:25:55 -04:00
Code Issues 490 Packages Projects Releases Wiki Activity

[GH-ISSUE #936] Documentation uses deprecated PlanningMiddleware instead of TodoListMiddleware #119

New Issue
Closed
opened 2026-02-17 17:19:13 -05:00 by yindo · 0 comments
yindo commented 2026-02-17 17:19:13 -05:00
Owner
Copy Link
Copy Source

Originally created by @bart0401 on GitHub (Oct 15, 2025).
Original GitHub issue: https://github.com/langchain-ai/docs/issues/936

Checked other resources

  • This is a bug, not a usage question.
  • I added a clear and descriptive title that summarizes this issue.
  • I used the GitHub search to find a similar question and didn't find it.
  • I am sure that this is a bug in LangChain rather than my code.
  • The bug is not resolved by updating to the latest stable version of LangChain (or the specific integration package).
  • This is not related to the langchain-community package.
  • I read what a minimal reproducible example is (https://stackoverflow.com/help/minimal-reproducible-example).
  • I posted a self-contained, minimal, reproducible example. A maintainer can copy it and run it AS IS.

Example Code

The official documentation shows this example:

from langchain.agents import create_agent
from langchain.agents.middleware import PlanningMiddleware

agent = create_agent(
    model="openai:gpt-4o",
    tools=[...],
    middleware=[PlanningMiddleware()],
)

result = agent.invoke({"messages": [HumanMessage("Help me refactor my codebase")]})
print(result["todos"])  # Array of todo items with status tracking

However, running this code fails with:

# Install: pip install langchain==1.0.0a15
from langchain.agents.middleware import PlanningMiddleware
# ImportError: cannot import name 'PlanningMiddleware' from 'langchain.agents.middleware'

The correct import in langchain==1.0.0a15:

from langchain.agents.middleware import TodoListMiddleware  # ✅ This exists

agent = create_agent(
    model="openai:gpt-4o",
    tools=[...],
    middleware=[TodoListMiddleware()],  # Changed from PlanningMiddleware
)

Error Message and Stack Trace (if applicable)

Traceback (most recent call last):
  File "test.py", line 2, in <module>
    from langchain.agents.middleware import PlanningMiddleware
ImportError: cannot import name 'PlanningMiddleware' from 'langchain.agents.middleware'
(/path/to/venv/lib/python3.11/site-packages/langchain/agents/middleware/__init__.py)

Description

Problem

The official LangChain documentation at https://docs.langchain.com/oss/python/langchain/middleware#planning uses PlanningMiddleware in code examples, but this class no longer exists in the codebase.

Root Cause

Based on the git history, PlanningMiddleware was renamed to TodoListMiddleware in commit fff87e95d1 (PR langchain-ai/langchain#33476) on October 14, 2025:

commit fff87e95d1
fix(langchain): rename `PlanningMiddleware` to `TodoListMiddleware` (#33476)

The code was updated, but the documentation was not synchronized with this change.

Impact

Users following the official documentation will encounter ImportError when trying to use the planning/todo middleware functionality.

Expected Behavior

Documentation should use TodoListMiddleware to match the actual implementation:

from langchain.agents.middleware import TodoListMiddleware

agent = create_agent(
    model="openai:gpt-4o",
    tools=[...],
    middleware=[TodoListMiddleware()],
)

Suggested Fix

Update the documentation at https://docs.langchain.com/oss/python/langchain/middleware#planning to:

  1. Replace all references to PlanningMiddleware with TodoListMiddleware
  2. Update import statements from: 
    from langchain.agents.middleware import PlanningMiddleware
    to: 
    from langchain.agents.middleware import TodoListMiddleware

Additional Context

The class is correctly exported in langchain/agents/middleware/__init__.py:

from .todo import TodoListMiddleware

__all__ = [
    # ...
    "TodoListMiddleware",
    # ...
]

The implementation is in /libs/langchain_v1/langchain/agents/middleware/todo.py with proper docstrings showing the correct usage.

System Info

System Information
------------------
> OS: Linux
> Python version: 3.11
> langchain_core: 1.0.0rc1
> langchain: 1.0.0a15
> langgraph: 1.0.0a4

Package Information
-------------------
> langchain==1.0.0a15
> langchain-core==1.0.0rc1

Installed from: pip
Originally created by @bart0401 on GitHub (Oct 15, 2025). Original GitHub issue: https://github.com/langchain-ai/docs/issues/936 ### Checked other resources - [x] This is a bug, not a usage question. - [x] I added a clear and descriptive title that summarizes this issue. - [x] I used the GitHub search to find a similar question and didn't find it. - [x] I am sure that this is a bug in LangChain rather than my code. - [x] The bug is not resolved by updating to the latest stable version of LangChain (or the specific integration package). - [x] This is not related to the langchain-community package. - [x] I read what a minimal reproducible example is (https://stackoverflow.com/help/minimal-reproducible-example). - [x] I posted a self-contained, minimal, reproducible example. A maintainer can copy it and run it AS IS. ### Example Code The [official documentation](https://docs.langchain.com/oss/python/langchain/middleware#planning) shows this example: ```python from langchain.agents import create_agent from langchain.agents.middleware import PlanningMiddleware agent = create_agent( model="openai:gpt-4o", tools=[...], middleware=[PlanningMiddleware()], ) result = agent.invoke({"messages": [HumanMessage("Help me refactor my codebase")]}) print(result["todos"]) # Array of todo items with status tracking ``` However, running this code fails with: ```python # Install: pip install langchain==1.0.0a15 from langchain.agents.middleware import PlanningMiddleware # ImportError: cannot import name 'PlanningMiddleware' from 'langchain.agents.middleware' ``` The **correct** import in `langchain==1.0.0a15`: ```python from langchain.agents.middleware import TodoListMiddleware # ✅ This exists agent = create_agent( model="openai:gpt-4o", tools=[...], middleware=[TodoListMiddleware()], # Changed from PlanningMiddleware ) ``` ### Error Message and Stack Trace (if applicable) ```python Traceback (most recent call last): File "test.py", line 2, in <module> from langchain.agents.middleware import PlanningMiddleware ImportError: cannot import name 'PlanningMiddleware' from 'langchain.agents.middleware' (/path/to/venv/lib/python3.11/site-packages/langchain/agents/middleware/__init__.py) ``` ### Description ### Problem The official LangChain documentation at https://docs.langchain.com/oss/python/langchain/middleware#planning uses `PlanningMiddleware` in code examples, but this class **no longer exists** in the codebase. ### Root Cause Based on the git history, `PlanningMiddleware` was renamed to `TodoListMiddleware` in commit `fff87e95d1` (PR langchain-ai/langchain#33476) on October 14, 2025: ```bash commit fff87e95d1 fix(langchain): rename `PlanningMiddleware` to `TodoListMiddleware` (#33476) ``` The code was updated, but the documentation was not synchronized with this change. ### Impact Users following the official documentation will encounter `ImportError` when trying to use the planning/todo middleware functionality. ### Expected Behavior Documentation should use `TodoListMiddleware` to match the actual implementation: ```python from langchain.agents.middleware import TodoListMiddleware agent = create_agent( model="openai:gpt-4o", tools=[...], middleware=[TodoListMiddleware()], ) ``` ### Suggested Fix Update the documentation at https://docs.langchain.com/oss/python/langchain/middleware#planning to: 1. Replace all references to `PlanningMiddleware` with `TodoListMiddleware` 2. Update import statements from: ```python from langchain.agents.middleware import PlanningMiddleware ``` to: ```python from langchain.agents.middleware import TodoListMiddleware ``` ### Additional Context The class is correctly exported in `langchain/agents/middleware/__init__.py`: ```python from .todo import TodoListMiddleware __all__ = [ # ... "TodoListMiddleware", # ... ] ``` The implementation is in `/libs/langchain_v1/langchain/agents/middleware/todo.py` with proper docstrings showing the correct usage. ### System Info ```bash System Information ------------------ > OS: Linux > Python version: 3.11 > langchain_core: 1.0.0rc1 > langchain: 1.0.0a15 > langgraph: 1.0.0a4 Package Information ------------------- > langchain==1.0.0a15 > langchain-core==1.0.0rc1 Installed from: pip ```
yindo added the bug label 2026-02-17 17:19:13 -05:00
yindo closed this issue 2026-02-17 17:19:13 -05:00
yindo changed title from Documentation uses deprecated `PlanningMiddleware` instead of `TodoListMiddleware` to [GH-ISSUE #936] Documentation uses deprecated `PlanningMiddleware` instead of `TodoListMiddleware` 2026-06-05 17:25:09 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
deepagents
docs-infra
external
external
help wanted
integration
internal
internal
javascript
js/ts
langchain
langgraph
langsmith
needs-title
pull-request
Mirrored from GitHub Pull Request
 python
reference
No Label bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/docs#119
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?