Skip to content

ant_ai.tools.builtins.planning_tool

Todo pydantic-model

Bases: BaseModel

One item of an agent's plan.

Show JSON schema:
{
  "description": "One item of an agent's plan.",
  "properties": {
    "content": {
      "description": "What has to be done.",
      "title": "Content",
      "type": "string"
    },
    "status": {
      "default": "pending",
      "description": "Where the item stands.",
      "enum": [
        "pending",
        "in_progress",
        "completed"
      ],
      "title": "Status",
      "type": "string"
    }
  },
  "required": [
    "content"
  ],
  "title": "Todo",
  "type": "object"
}

Fields:

  • content (str)
  • status (Literal['pending', 'in_progress', 'completed'])
Source code in src/ant_ai/tools/builtins/planning_tool.py
19
20
21
22
23
24
25
class Todo(BaseModel):
    """One item of an agent's plan."""

    content: str = Field(description="What has to be done.")
    status: Literal["pending", "in_progress", "completed"] = Field(
        default="pending", description="Where the item stands."
    )

content pydantic-field

content: str

What has to be done.

status pydantic-field

status: Literal["pending", "in_progress", "completed"] = (
    "pending"
)

Where the item stands.

PlanStore pydantic-model

Bases: BaseModel

Keeps the plans as files, one per agent and conversation: <root>/<agent>/<session_id>.md.

Show JSON schema:
{
  "description": "Keeps the plans as files, one per agent and conversation: `<root>/<agent>/<session_id>.md`.",
  "properties": {
    "root": {
      "default": ".plans",
      "description": "Folder of the plans.",
      "format": "path",
      "title": "Root",
      "type": "string"
    }
  },
  "title": "PlanStore",
  "type": "object"
}

Fields:

Source code in src/ant_ai/tools/builtins/planning_tool.py
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
class PlanStore(BaseModel):
    """Keeps the plans as files, one per agent and conversation: `<root>/<agent>/<session_id>.md`."""

    root: Path = Field(default=Path(".plans"), description="Folder of the plans.")

    def path(self, agent: str, session_id: str) -> Path:
        """The file of the plan of `agent` in the conversation `session_id`."""
        return self.root / _file_name(agent) / f"{_file_name(session_id)}.md"

    def read(self, agent: str, session_id: str) -> str | None:
        """The plan, or None if there is none."""
        try:
            text: str = self.path(agent, session_id).read_text(encoding="utf-8")
        except OSError:
            return None
        return text or None

    def write(self, agent: str, session_id: str, text: str) -> None:
        """Save the plan, replacing the previous one."""
        write_atomic(self.path(agent, session_id), text)

    def delete(self, agent: str, session_id: str) -> None:
        """Remove the plan, if there is one."""
        self.path(agent, session_id).unlink(missing_ok=True)

root pydantic-field

root: Path = Path('.plans')

Folder of the plans.

path

path(agent: str, session_id: str) -> Path

The file of the plan of agent in the conversation session_id.

Source code in src/ant_ai/tools/builtins/planning_tool.py
48
49
50
def path(self, agent: str, session_id: str) -> Path:
    """The file of the plan of `agent` in the conversation `session_id`."""
    return self.root / _file_name(agent) / f"{_file_name(session_id)}.md"

read

read(agent: str, session_id: str) -> str | None

The plan, or None if there is none.

Source code in src/ant_ai/tools/builtins/planning_tool.py
52
53
54
55
56
57
58
def read(self, agent: str, session_id: str) -> str | None:
    """The plan, or None if there is none."""
    try:
        text: str = self.path(agent, session_id).read_text(encoding="utf-8")
    except OSError:
        return None
    return text or None

write

write(agent: str, session_id: str, text: str) -> None

Save the plan, replacing the previous one.

Source code in src/ant_ai/tools/builtins/planning_tool.py
60
61
62
def write(self, agent: str, session_id: str, text: str) -> None:
    """Save the plan, replacing the previous one."""
    write_atomic(self.path(agent, session_id), text)

delete

delete(agent: str, session_id: str) -> None

Remove the plan, if there is one.

Source code in src/ant_ai/tools/builtins/planning_tool.py
64
65
66
def delete(self, agent: str, session_id: str) -> None:
    """Remove the plan, if there is one."""
    self.path(agent, session_id).unlink(missing_ok=True)

PlanningTool pydantic-model

Bases: Tool

Lets the agent keep a plan for a long task, saved as one file per conversation.

Added with its PlanningHook by Agent(planning=True). The agent can then call:

- PlanningTool_write_todos(todos=[{"content": "fix the bug", "status": "in_progress"}])
Show JSON schema:
{
  "$defs": {
    "PlanStore": {
      "description": "Keeps the plans as files, one per agent and conversation: `<root>/<agent>/<session_id>.md`.",
      "properties": {
        "root": {
          "default": ".plans",
          "description": "Folder of the plans.",
          "format": "path",
          "title": "Root",
          "type": "string"
        }
      },
      "title": "PlanStore",
      "type": "object"
    }
  },
  "description": "Lets the agent keep a plan for a long task, saved as one file per conversation.\n\nAdded with its `PlanningHook` by `Agent(planning=True)`. The agent can then call:\n\n    - PlanningTool_write_todos(todos=[{\"content\": \"fix the bug\", \"status\": \"in_progress\"}])",
  "properties": {
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Tool name.",
      "title": "Name"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Tool description. Is used by the LLM to decide whether to call or not the specific tool.",
      "title": "Description"
    },
    "parameters": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The parameters needed by the tool. This is a self-constructed field.",
      "title": "Parameters"
    },
    "agent": {
      "description": "Name of the agent; each agent has its own plans.",
      "title": "Agent",
      "type": "string"
    },
    "store": {
      "$ref": "#/$defs/PlanStore",
      "description": "Where the plans are kept."
    }
  },
  "required": [
    "agent"
  ],
  "title": "PlanningTool",
  "type": "object"
}

Fields:

Validators:

  • _set_defaults
Source code in src/ant_ai/tools/builtins/planning_tool.py
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class PlanningTool(Tool):
    """
    Lets the agent keep a plan for a long task, saved as one file per conversation.

    Added with its `PlanningHook` by `Agent(planning=True)`. The agent can then call:

        - PlanningTool_write_todos(todos=[{"content": "fix the bug", "status": "in_progress"}])
    """

    agent: str = Field(description="Name of the agent; each agent has its own plans.")
    store: PlanStore = Field(
        default_factory=PlanStore, description="Where the plans are kept."
    )

    def write_todos(
        self, todos: list[Todo], ctx: InvocationContext | None = None
    ) -> str:
        """Write the full plan for the current task, replacing the previous one. Use it at the start of a task with several steps, and again whenever an item starts or is done. Keep exactly one item `in_progress` while working."""
        # Tool arguments reach the method as parsed JSON, not as models.
        items: list[Todo] = [Todo.model_validate(t) for t in todos]
        if sum(t.status == "in_progress" for t in items) > 1:
            raise ToolError("only one item can be in_progress at a time")
        text: str = render_plan(items)
        # Without a conversation there is no next message to keep the plan for:
        # the model sees it in this result.
        if ctx is None:
            return text or "Plan cleared."
        if not items:
            self.store.delete(self.agent, ctx.session_id)
            return "Plan cleared."
        if all(t.status == "completed" for t in items):
            self.store.delete(self.agent, ctx.session_id)
            return f"{text}\n\nAll items are completed, so the plan is cleared."
        self.store.write(self.agent, ctx.session_id, text)
        return text

agent pydantic-field

agent: str

Name of the agent; each agent has its own plans.

store pydantic-field

store: PlanStore

Where the plans are kept.

write_todos

write_todos(
    todos: list[Todo], ctx: InvocationContext | None = None
) -> str

Write the full plan for the current task, replacing the previous one. Use it at the start of a task with several steps, and again whenever an item starts or is done. Keep exactly one item in_progress while working.

Source code in src/ant_ai/tools/builtins/planning_tool.py
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def write_todos(
    self, todos: list[Todo], ctx: InvocationContext | None = None
) -> str:
    """Write the full plan for the current task, replacing the previous one. Use it at the start of a task with several steps, and again whenever an item starts or is done. Keep exactly one item `in_progress` while working."""
    # Tool arguments reach the method as parsed JSON, not as models.
    items: list[Todo] = [Todo.model_validate(t) for t in todos]
    if sum(t.status == "in_progress" for t in items) > 1:
        raise ToolError("only one item can be in_progress at a time")
    text: str = render_plan(items)
    # Without a conversation there is no next message to keep the plan for:
    # the model sees it in this result.
    if ctx is None:
        return text or "Plan cleared."
    if not items:
        self.store.delete(self.agent, ctx.session_id)
        return "Plan cleared."
    if all(t.status == "completed" for t in items):
        self.store.delete(self.agent, ctx.session_id)
        return f"{text}\n\nAll items are completed, so the plan is cleared."
    self.store.write(self.agent, ctx.session_id, text)
    return text

render_plan

render_plan(todos: list[Todo]) -> str

The plan as a checklist, one item per line.

Source code in src/ant_ai/tools/builtins/planning_tool.py
28
29
30
def render_plan(todos: list[Todo]) -> str:
    """The plan as a checklist, one item per line."""
    return "\n".join(f"- {_MARK[t.status]} {t.content}" for t in todos)