States

A shared context used inside Pools for smarter routing decisions.

State is a shared workspace used only inside Pools. It exists for the duration of a single pool.run() call and gives Routers the information they need to make intelligent routing decisions.

Think of State as a scratchpad that all agents in a pool share, Routers can read and write to it, while Agents and Tools cannot.

State is automatically created by the Pool and passed to:

Custom Router functions
Routing Agents

So in that sense, no configuration is required.

Where State Can Be Used

Custom Router functions

def custom_router(state, call_count, last_result):
    # Read history
    last_message = state.history[-1]["content"]

    # Store workflow progress
    state.set("stage", "analysis")

    # Read agent capabilities
    print(state.agents.keys())

    return RouterResult("Researcher")

Refer the API Reference of State to know more about what can be stored in State.

Manual State Creation (highly optional)

from peargent import State

custom_state = State(data={"stage": "init"})

pool = create_pool(
    agents=[agent1, agent2],
    default_state=custom_state
)

State API Reference

The State object provides a small but powerful API used inside Pools and Routers.

Methods

Methods give routers the ability to store and retrieve custom information needed for routing decisions.

Name	Type	Inputs	Returns	Description
`add_message`	Method	`role: str`, `content: str`, `agent: str \| None`	`None`	Appends a message to `state.history` and persists it if a history manager exists.
`get`	Method	`key: str`, `default: Any = None`	`Any`	Retrieves a value from the key-value store. Returns `default` if the key is missing.
`set`	Method	`key: str`, `value: Any`	`None`	Stores a value in the key-value store. Useful for workflow tracking, flags, and custom router logic.

Attributes

Attributes give routers visibility into what has happened so far (history, agents, persistent history, custom data).

Name	Type	Read/Write	Description
`kv`	`dict[str, Any]`	Read/Write (via get/set recommended)	Internal key-value store for custom state. Use `state.get()`/`state.set()` instead of accessing directly.
`history`	`list[dict]`	Read-only (managed by Pool)	In-memory conversation history for the current pool run. Contains `role`, `content`, and optional `agent`.
`history_manager`	`ConversationHistory \| None`	Read-only	Optional persistent history backend (SQLite, Redis, PostgreSQL, etc.). Used automatically by Pool.
`agents`	`dict[str, Agent]`	Read-only	Mapping of agent names to their Agent objects. Useful for advanced routing logic (e.g., route based on tools or descriptions).

Message Structure (`state.history`)

Each entry in state.history looks like:

{
  "role": "user" | "assistant" | "tool",
  "content": "message content",
  "agent": "AgentName"  # only for assistant/tool messages
}