Todo Lists

When Amara tackles a goal that spans several steps, it maintains an internal todo list to keep itself organized. Each item captures a discrete piece of work and a status — pending, in progress, or completed. The Syntic Agent SDK surfaces this list as structured events, so your application can display progress, drive a UI, or verify that the agent is working through the plan you expected.

Why the agent keeps a list

Multi-step tasks are where agents most often lose the thread — they finish one subtask and forget another, or repeat work already done. An explicit todo list is the agent’s working memory for the plan. It helps Amara sequence work, avoid dropping requirements, and stay coherent across a long run. As a developer you benefit twice: the agent performs better, and you get a live window into its intentions.

Reading todo updates

The SDK emits a message whenever the todo list changes. Watch for it to render progress or to log the plan for later review.

import { query } from "@syntic/agent-sdk";
 
for await (const message of query({
  prompt: "Add pagination to the users API, with tests and docs.",
})) {
  if (message.type === "todo_update") {
    for (const item of message.todos) {
      console.log(`[${item.status}] ${item.content}`);
    }
  }
}

async for message in query(
    prompt="Add pagination to the users API, with tests and docs.",
):
    if message.type == "todo_update":
        for item in message.todos:
            print(f"[{item.status}] {item.content}")

Using todos in your product

In an interactive tool, the todo list makes an excellent progress indicator — far more meaningful than a spinner, because it tells the user what the agent is actually doing and what remains. In automated pipelines, you can assert on the list to confirm the agent addressed every requirement before you accept its output. Because todos are just structured data, they also feed naturally into your telemetry, letting you analyze how tasks decompose across many runs.