Skip to main content
Agent State is a set of typed fields the agent is responsible for keeping up to date throughout a session. Define the fields on the agent’s State tab in the Portal; the agent fills them in as it converses and runs capabilities. State acts as a structured scratchpad that persists across turns, so the agent never loses track of critical information — and it feeds directly into how the agent behaves:
  • Orchestration — in reasoning mode, the planner sees current state when deciding what to do next, and the Process step writes updates back after each action.
  • Routing — in route mode, rules-based routing can match on state values (e.g. route to the billing action once order_id is set).
  • SDK — read resolved state and seed values per request via agent.get (see below).

​
Defining a field

Each state field has:
  • Name — how the agent and your code reference the field (e.g. order_id).
  • Description — what the field holds and when to fill it. The agent relies on this, so be specific.
  • Type — string, number, boolean, or date. Values written from the SDK are validated against this type.
  • Update Rules (optional) — extra guidance for when and how the agent should update the value.
  • Read / Write Scope — access control, below.

​
Access control (ACLs)

Each field carries its own ACL controlling which agents in the hierarchy can see or modify it — critical for data integrity in multi-agent workflows.
  • Read Scope — who can view the field’s value.
  • Write Scope — who can update it. Write access requires read access.
Both scopes support three levels:
  1. Private (default): only the agent that defines the field can access it. Best for internal session state that sub-agents shouldn’t see.
  2. Public: any agent in the session hierarchy can access the field. Useful for shared context like user_id or session_language.
  3. Custom: explicitly select which sub-agents get access — a “need-to-know” architecture where data is only shared with the specialists that require it.

​
Use cases

  • Data isolation: keep sensitive internal reasoning Private.
  • Selective delegation: share payment_token with only the “Billing” sub-agent via Custom, hidden from “General Support”.
  • Global context: make essential metadata Public so every agent in the tree can use it.

​
Seeding state from code

You can read an agent’s resolved state and seed field values for a single request through the SDK: 
agent = client.agent.get("YOUR_AGENT_NAME", version="prod")
agent.state["user_facts"] = "VIP customer since 2021"

request = agent.to_request(messages=[...], session_id="YOUR_SESSION_ID")
response = client.agent.completions.create(request=request)
Patches are field-level and validated against the field types defined on the State tab: absent keys are untouched, and an explicit None clears a field. See Agent Call — per-request overlays.

​
Next