Skip to main content

Thread State (agentvisor.state)

Thread-scoped key-value storage backed by the Temporal ThreadWorkflow. Values written in one thread are never visible from another thread — the thread's own gRPC connection binds the key space, the same way it does for AgentVisorCheckpointer (see Thread ID).

This is the Python SDK layer over the same mechanism the State API exposes over HTTP; use this module from agent code, and the HTTP endpoints from an external caller.

Usage​

from agentvisor import ThreadStateStore

store = ThreadStateStore()
store.put_json("counter", {"count": 42})
value = store.get_json("counter")  # {"count": 42}
store.delete("counter")
keys = store.list(prefix="session:")

ThreadStateStore is a JSON-serializing convenience wrapper — use it for structured Python objects (dicts, lists, primitives). For raw bytes, use ThreadStateClient directly:

from agentvisor.state import ThreadStateClient

client = ThreadStateClient()
client.put("raw-key", b"\x00\x01\x02")
data = client.get("raw-key")  # bytes | None

API Reference​

Classes​

ThreadStateClient​

Low-level bytes-oriented client. Wraps the four State gRPC RPCs (StateGet, StatePut, StateDelete, StateList); callers are responsible for serialization.

class ThreadStateClient:
    def __init__(self, client: AgentClient | None = None): ...
    def get(self, key: str) -> bytes | None: ...
    def put(self, key: str, value: bytes) -> None: ...
    def delete(self, key: str) -> None: ...
    def list(self, prefix: str = "") -> list[str]: ...

ThreadStateStore​

JSON-serializing convenience wrapper over ThreadStateClient.

class ThreadStateStore:
    def __init__(self, client: AgentClient | None = None): ...
    def get_json(self, key: str) -> Any | None: ...
    def put_json(self, key: str, value: Any) -> None: ...
    def delete(self, key: str) -> None: ...
    def list(self, prefix: str = "") -> list[str]: ...

get_json() raises json.JSONDecodeError if the stored value isn't valid JSON (for example, one written via ThreadStateClient.put() directly); put_json() raises TypeError if value isn't JSON-serializable. Both classes accept an optional client: AgentClient for injecting a specific connection — the default uses the global client from agentvisor.client.get_client().

See Also​