Skip to content

Todos

The Todos plugin gives the agent a todo_write tool and keeps the current list in view. When the agent writes a list, the plugin re-surfaces it before each model call, so on a long task the agent keeps its plan in front of it without restating it.

Todos has two halves. The todo_write tool writes the whole list to agent state, replacing whatever was there. Before each model call, an internal Context Injector renders that list back as a <system-reminder>.

Re-surfacing goes through injection rather than editing the conversation 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. Each rendered list is stored as an injected block, and only the latest user message’s injected blocks are sent to the model — older ones are dropped from the request. The lists stay readable in the stored messages for anything inspecting history.

The injector fires on every turn, not just fresh user asks: the agent updates the list mid-loop via todo_write, so it should see the refreshed list on the next model call within the same invocation.

Pass a Todos to your agent’s plugins list. There is nothing to configure — the tool and the injector are both registered for you:

from strands import Agent
from strands.vended_plugins.todos import Todos
agent = Agent(plugins=[Todos()])
agent("Refactor the auth module, then update its tests and the changelog.")

The tool description steers the agent to use the list for multi-step work (roughly three or more distinct steps), keep exactly one item in progress at a time, update status as it goes rather than batching, and clear the list when the work is done.

Each call to todo_write passes the full updated list. An item has three fields:

FieldPurpose
contentThe task, imperative: "Run tests".
activeFormPresent continuous, shown while the item is in progress: "Running tests".
statuspending, in_progress, or completed.

Two forms of the same task sounds redundant, but it is what makes the rendered list readable as a status line: a completed or pending item shows its content, and the one item in progress shows its activeForm. Passing an empty list clears the state.

The list lives in agent state under a plain key, so your application can read it to render progress in a UI. It is a list of items in the shape above, or absent if the agent has not written one yet:

todos = agent.state.get("todos") or []
for todo in todos:
print(todo["status"], todo["content"])

Because state is per-agent rather than on the plugin, one Todos instance is safe to share across agents — each agent keeps its own list.

FieldPurpose
namePlugin name. It also tags the reminder blocks the plugin injects, and that tag is what keeps a retry or a restored session from injecting a second copy — so keep it stable. Defaults to 'strands:todos'.
state_keystateKeyAgent-state key the list is stored under. Defaults to 'todos'. Set it to avoid colliding with another consumer of that key.

One agent takes one Todos. The tool is always named todo_write, so adding a second instance to the same agent raises, regardless of what name and state_keystateKey are set to.