Stateful Tools in a Stateless Model

~16 min · conversation, tools, state

Level 0Apprentice

0 XP0/100 lessons0/14 achievements

0/120 XP to next level120 XP to go0% complete

The model has no state; the tools do

The model is a function from messages to messages. Any state — current draft, partial form, in-progress order — lives outside, accessed via tools. This split is the point of agent design: stateless model, stateful environment.

Stateful-tool patterns

Drafts — create_draft, update_draft, send_draft. Model can iterate without re-stating the whole draft each turn.
Sessions — start_session, step_session, finish_session. The session id is the handle.
Carts / forms — entity has its own lifecycle; tools mutate it; model navigates by id.

Why this beats packing everything into context

Less context = lower cost, faster response.
Auditable state changes (the tool calls are the diff).
Resumable — close the conversation, come back, pick up the draft.
Concurrent — two agents can act on different parts of the same state.

Code

Stateful draft tools·python

@tool
def create_draft(subject: str) -> dict:
    return {"draft_id": db.drafts.create(subject)}

@tool
def update_draft(draft_id: str, body: str) -> dict:
    db.drafts.update(draft_id, body=body)
    return {"draft_id": draft_id, "status": "updated"}

@tool
def send_draft(draft_id: str) -> dict:
    return db.drafts.send(draft_id)

External links

Exercise

Take an agent that re-injects entity state every turn. Move state to stateful tools (create / update / get). Measure context size and cost change.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousRe-Anchoring at Each Turn Next →The Pippa Pattern — Vault as External Memory

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.