Designing State
State design determines what information the agent tracks throughout its execution. The state schema should be designed before writing agent logic.
6 min•By Priygop Team•Updated 2026
State Design Principles
- Start minimal: only include state fields that are actively used by at least one step
- Type every field: define the type and format of every field (string, float, dict, list)
- Define defaults: what is the initial value of every field?
- Define lifecycle: when is each field written? When is it read? When does it expire?
- Plan for failure: include retry_counts, errors, and last_error fields from the start
- Plan for audit: include created_at, updated_at, and step counter fields
State Schema Example
State Schema Example
from dataclasses import dataclass, field
from typing import Optional, List
@dataclass
class RefundAgentState:
# Task identity
task_id: str
started_at: str
# Input (set at start, never changed)
order_id: str
user_id: str
reason: str
# Execution
step: int = 0
max_steps: int = 12
status: str = "running" # running|complete|failed|escalated|waiting
# Order data (populated by get_order)
order: Optional[dict] = None
order_found: bool = False
# Eligibility (populated by check_policy)
eligible: Optional[bool] = None
rejection_reason: Optional[str] = None
# Refund data (populated by issue_refund)
refund_id: Optional[str] = None
amount_refunded: float = 0.0
# Communication (populated by send_email)
email_sent: bool = False
# Error tracking
retry_counts: dict = field(default_factory=dict)
errors: List[dict] = field(default_factory=list)
last_error: Optional[str] = None
# Escalation
escalation_reason: Optional[str] = None
escalation_id: Optional[str] = None
# Result
outcome: Optional[str] = None
message: Optional[str] = None
# Create initial state
state = RefundAgentState(
task_id="TASK-001",
started_at="2024-01-15T10:00:00Z",
order_id="ORD-123",
user_id="U-001",
reason="product damaged"
)
print(f"State initialised for task: {state.task_id}")
print(f"Order: {state.order_id}, Status: {state.status}, Step: {state.step}")Key Takeaways
- State design determines what information the agent tracks throughout its execution.
- Start minimal: only include state fields that are actively used by at least one step
- Type every field: define the type and format of every field (string, float, dict, list)
- Define defaults: what is the initial value of every field?