Intermediate7 min

Custom State

Agents track more than messages. Extend AgentState with custom fields to carry user preferences, task progress, or any data your tools and middleware need across the conversation.

Quick Reference

→Default AgentState has two fields: messages (list) and remaining_steps (int)
→Extend it with a TypedDict that subclasses AgentState
→state_schema=CustomState on create_agent — simple shortcut for tool-only state
→Middleware with state_schema = CustomState — preferred when middleware needs the state
→Custom state fields are available to all tools and middleware in the same agent

What AgentState Is

Every agent carries a state object throughout the conversation. By default it has two fields: messages (the full message history) and remaining_steps (how many more iterations the agent can run). That's enough for simple agents — but production agents often need to track additional data: which user is talking, what preferences they've set, what the agent has already fetched, or what task stage it's in. Custom state is how you add those fields.

Default AgentState — what every agent starts with

Defining State via state_schema

The quickest way to add custom state: pass state_schema to create_agent. Use this when your extra fields are only needed inside tools — no middleware involved.

Defining State via Middleware (Preferred)

When your custom state is used by middleware hooks — not just tools — define it on the middleware class itself. This keeps state extensions scoped to the middleware that owns them, and makes the relationship explicit.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.