strands.vended_plugins.todos.plugin
Todos plugin for maintaining a structured task list across a multi-step run.
A single todo_write tool writes the current list to agent state; an internal
ContextInjector re-renders that list at intervals, so the agent keeps its plan in view without
restating it.
Re-surfacing goes through ContextInjector rather than editing agent.messages directly.
The list is rewritten on every todo_write call, so what matters is that the model sees one
current copy rather than a pile of superseded ones. Injection gives that: each rendered list is
stored as an injected block, and only the latest user message’s injected blocks are sent as
text — older ones are dropped from the request. The lists stay readable in agent.messages
for anything inspecting history, and callers that do not want them can skip any block where
"injected" in block.
The reminder is paced in model calls, not user turns, so a long single invocation gets it
mid-loop. The model last saw the list on the call after a todo_write or in a reminder; the
next reminder waits reminder_interval model calls after that, since repeating a list the model
has just read only costs tokens.
TodoItem
Section titled “TodoItem”class TodoItem(TypedDict)Defined in: src/strands/vended_plugins/todos/plugin.py:42
One entry in the task list.
Attributes:
content- The task, imperative: “Run tests”.activeForm- Present continuous, shown while the item is in progress: “Running tests”.status- Where the item stands.
class Todos(Plugin)Defined in: src/strands/vended_plugins/todos/plugin.py:66
Gives the agent a todo_write tool and keeps the current list in view.
The tool persists the list to agent.state under state_key; every reminder_interval
model calls, counted from the call that last showed the list, the plugin re-renders it as a
<system-reminder>. Sharing one instance across agents is safe: the list lives in per-agent
state, not on the plugin.
One agent takes one Todos. The tool is always named todo_write, so a second instance
raises no matter how name and state_key are set.
A reminder changes the tail of the request it is sent with. On a provider without explicit
cache points that moves the cached prefix boundary, so a lower reminder_interval trades
cache hits and tokens for a fresher list.
Example:
from strands import Agentfrom strands.vended_plugins.todos import Todos
agent = Agent(plugins=[Todos()])Arguments:
name- Plugin name. It also tags the reminder blocks the plugin injects, and that tag keeps a retry or a restored session from injecting a second copy, so keep it stable. Defaults to"strands:todos".state_key- Agent-state key the list is stored under. Defaults to"todos".reminder_interval- Re-render the list every this many model calls, counted from the call that last showed it: the one after atodo_writecall, or a reminder.1re-renders it on every call that does not already carry atodo_writeresult. Defaults to10.
Raises:
ValueError- Ifreminder_intervalis not a positive integer.
__init__
Section titled “__init__”def __init__(*, name: str = _DEFAULT_NAME, state_key: str = _STATE_KEY, reminder_interval: int = _DEFAULT_REMINDER_INTERVAL) -> NoneDefined in: src/strands/vended_plugins/todos/plugin.py:103
Initialize the plugin.
@propertydef name() -> strDefined in: src/strands/vended_plugins/todos/plugin.py:120
Plugin name, also the tag on the reminder blocks the plugin injects.
init_agent
Section titled “init_agent”def init_agent(agent: Agent) -> NoneDefined in: src/strands/vended_plugins/todos/plugin.py:124
Register the re-surfacing injector. The todo_write tool is auto-registered.
Raises:
ValueError- If the agent already has atodo_writetool. The plugin registry’s duplicate check is onname, which a second instance can set freely, so the tool name is checked here instead.
todo_write
Section titled “todo_write”@tool(name="todo_write", context="tool_context")def todo_write(todos: list[TodoItem], tool_context: ToolContext) -> strDefined in: src/strands/vended_plugins/todos/plugin.py:173
Create and maintain a structured task list for the current session.
Use proactively for multi-step work (roughly 3+ distinct steps). Keep exactly one item
in_progress at a time, and update status as you go rather than batching. The current
list is re-surfaced to you periodically, so you do not need to restate it. Pass an empty
list to clear it when the work is done.
Arguments:
todos- The full updated list. Each item hascontent(the task, imperative: “Run tests”),activeForm(present continuous, shown while in progress: “Running tests”), andstatus(pending,in_progress,completed).tool_context- Injected by the framework. Not user-facing.
Returns:
The number of items still open, followed by the rendered list.