Skip to main content

​
Create State

Create state for a task. 
state = client.states.create(
    task_id="task-uuid",
    agent_id="agent-uuid",
    state={"key": "value", "count": 0},
)
Parameters:
  • task_id (str): Task UUID
  • agent_id (str): Agent UUID
  • state (dict): State data
Returns: State

​
Retrieve State

Get state by task and agent. 
state = client.states.retrieve(
    task_id="task-uuid",
    agent_id="agent-uuid",
)
Parameters:
  • task_id (str): Task UUID
  • agent_id (str): Agent UUID
Returns: State or None

​
Update State

Update existing state. 
state = client.states.update(
    state_id="state-uuid",
    state={"key": "new_value", "count": 1},
)
Parameters:
  • state_id (str): State UUID
  • state (dict): New state data
Returns: State

​
List States

List states for a task or agent. 
states = client.states.list(
    task_id="task-uuid",
)
Parameters:
  • task_id (str, optional): Filter by task
  • agent_id (str, optional): Filter by agent
  • limit (int, optional): Max results
  • page_number (int, optional): Page number
Returns: StateListResponse

​
Delete State

Delete state. 
client.states.delete("state-uuid")
Parameters:
  • state_id (str): State UUID
Returns: State

​
State Model

state.id          # State UUID
state.task_id     # Parent task
state.agent_id    # Associated agent
state.state       # State data (dict)
state.created_at  # Creation timestamp
state.updated_at  # Last update

​
Usage Patterns

​
Initialize on Create

# In agent handler
@server.on_create
async def handle_create(ctx: TaskContext, params: dict):
    await ctx.state.create(state={
        "initialized": True,
        "step": 1,
        "history": [],
    })

​
Get and Update

@server.on_event
async def handle_event(ctx: TaskContext, event: Event):
    state = await ctx.state.get()
    if state is None:
        return

    history = state.state.get("history", [])
    history.append(event.content.content)

    await ctx.state.update({
        **state.state,
        "history": history,
    })

​
Best Practices

State is stored as JSON. Keep state small and serializable.
State is scoped to a single task. Use external storage for cross-task data.