STATEK Core Concepts

STATEK is built around one simple idea: an LLM agent runs Python in a durable workspace.

A job can start with local variables already available. Application code can supply those variables directly, or a coordinator/dispatcher agent can pick a queued task and create a new job with the right task context. The working agent can then use those variables, call tools, import or call connected code, create new variables, print output, and update dbzero-backed objects. STATEK stores the execution state so later steps can continue from the same Python context.

The mental model

Think of a STATEK job as a persisted Python session for one unit of agent work.

# Startup locals supplied by application code or prepared from a queued task
user
message
calendar
today
timestamp

The agent sees a workspace where those names already exist. It does not need to ask for a JSON tool call just to get back a string version of the calendar. If a calendar object is put in context, the agent can use that object as Python.

events = calendar.events_for(today)
print(events)

If the agent creates more variables, those variables become part of the job's Python state:

meeting = calendar.find_meeting("Weekly planning", day=today)
empty_slot = calendar.find_empty_slot(
    after=meeting.ends_at,
    duration=meeting.duration,
)

On a later step, the same job can still use meeting and empty_slot.

meeting.move_to(empty_slot)
print(meeting.starts_at)

That is the working model. The rest of the STATEK objects exist to make this durable, inspectable, and controllable.

Agent

An Agent describes the Python workspace the model is allowed to use. It carries:

• role: the agent's role name
• _system_prompt: instructions for how the agent should work
• _tools: Python callables exposed to the model
• _internal_tools: Python callables available in execution but hidden from model-facing tool descriptions
• _metadata: model/provider configuration, including MODEL
• context: agent-specific runtime context, such as adapters or private tool objects

The important part is that tools are Python functions, not a separate workflow language. A tool can return a string, a number, a dbzero object, a domain object, or whatever controlled value your application wants the agent to use.

from statek import tool
 
@tool
def current_time(**kwargs):
    return datetime.now()
 
@tool
def reserve_room(meeting, room, **kwargs):
    meeting.room = room

If these are exposed to the agent, the agent can call them from Python steps.

Job definition

A JobDef is the frozen setup for one task. It ties the agent to:

• model metadata
• prompt parameters
• optional warmup code
• chat style
• locale
• task-specific context setup

For conceptual purposes, this is where the job setup decides what the job is about and what should exist before the working agent starts. That setup can be done directly by application code, or by another agent that picked work from a queue.

# Conceptual startup context
user = current_user
message = queued_message
calendar = current_user.calendar
today = request_date
timestamp = queued_message.created_at

In real STATEK code, startup context can be provided through warmup code, shared variables, job local state, or tools that initialize context from queued events. The result is the same for the working agent: useful names are available in its Python workspace.

Job

A Job is the durable execution unit. It is the object you inspect when you want to know what happened.

It stores:

• the JobDef
• the current status
• the Python execution environment
• chat history and tool results
• usage and cost information where available
• errors
• parent/child job relationships
• continuation fields for suspended work

Conceptually, it is the persisted notebook kernel for the agent's task.

job.status
job.py_env.local_state
job.py_env.console
job.chat_log
job.error

Each job is isolated from other jobs at the Python-state level. If two jobs both use a variable named calendar, those variables live in different PyEnv.local_state dictionaries.

# Job A
job_a.py_env.local_state["calendar"]
 
# Job B
job_b.py_env.local_state["calendar"]

The two jobs can run in the same process without sharing local variables unless the application deliberately points them at the same durable object or external resource.

Python execution environment

PyEnv is where the Python workspace lives.

The most important field is local_state. It holds the variables the agent can reuse:

job.py_env.local_state["user"]
job.py_env.local_state["calendar"]
job.py_env.local_state["today"]
job.py_env.local_state["meeting"]
job.py_env.local_state["empty_slot"]

PyEnv also stores:

• global_state: persistent globals for executed code
• console: captured Python output
• exceptions: execution errors keyed by chat-log position
• push_log: messages pushed into an active job
• exit_status: the result set when code calls exit(...)
• continuation fields used when execution pauses and later resumes

The plain-language version: STATEK remembers the variables and output from the agent's Python session.

Many concurrent jobs

STATEK's job loop can coordinate many jobs in one process. It looks for jobs that are ready, warming up, started, or suspended; it unsuspends jobs whose waiting condition is ready; and it schedules runnable jobs with a configured concurrency limit.

The important property is that jobs do not interfere with each other's Python variables. Every job has its own:

• Job object
• PyEnv.local_state
• console output
• chat and tool log
• status and continuation fields
• error state

So one process can manage many independent agent jobs at once. Large fleets can include thousands of persisted jobs waiting, ready, or moving through execution, while the runner limits how many are actively executing at the same moment. Capacity is operational: it depends on memory, dbzero storage, model/provider latency, tool latency, and the configured max_concurrency.

dbzero objects

Durable application state is just Python objects backed by dbzero.

import dbzero as db0
 
@db0.memo
class Calendar:
    def __init__(self):
        self.events = []
 
    def events_for(self, day):
        return [event for event in self.events if event.day == day]

The agent does not need to know about storage layout to use this object:

events = calendar.events_for(today)

If calendar and its events are dbzero-backed objects, changes to them are durable application state. If the agent stores calendar or meeting in job locals, the job can also resume with those variables still available.

Chat log, console, and tool log

STATEK keeps separate records for different parts of execution:

• chat_log: user messages, LLM responses, warmup entries, and subtask notifications
• console: output printed by executed Python
• tool_log: tool results or tool errors attached to the chat item that caused them
• push_log: pushed messages that should appear in later context

This makes the job inspectable. You can see what the model answered, what Python it ran, what it printed, which tools it called, and which variables remain available.

Job lifecycle

Jobs move through persisted statuses:

• READY: created and ready to run
• WARMING_UP: startup or warmup code is running
• STARTED: active model or Python execution is underway
• SUSPENDED: waiting for a future, callback, external event, or delegated result
• DONE: the current unit of work completed

The status is durable. A worker can stop while a job is waiting, and another worker can later inspect and continue the same job state.

Futures, callbacks, and suspended jobs

Some work cannot complete immediately. A job may wait for a human approval, a callback, a subtask, or a future-like result.

When that happens, STATEK records continuation state such as:

• what result the job is waiting for
• which instruction should resume next
• which warmup block was active, if suspension happened during warmup

Futures and temporals are lower-level building blocks. Public application flows should usually explain the human or external event first, then describe the continuation mechanism only when needed.

Subtasks and delegated work

A job can create child jobs for delegated work. The parent keeps a durable handle to the child through a SubTaskHandler.

The handler records whether the child is waiting, started, completed, or failed. When the child completes, the parent receives a notification that becomes part of the parent's chat history.

The practical effect is that an agent can ask another agent to work, pause, and later continue with the child result in the same durable Python workflow.

What is durable, and what is not

Durable:

• Python locals in the job
• console output
• chat and tool history
• job status and continuation fields
• dbzero-backed application objects
• errors and usage information
• parent/child job links

Not automatic:

• deterministic replay of external side effects
• full process isolation for untrusted code
• tenant isolation
• retries for emails, payments, files, or third-party APIs

Where to go next

Use Quickstart for a minimal durable job, then read Jobs, Agents, and Tools. For interruption and recovery boundaries, continue to Callbacks and Interruptions, Subtasks, Futures, Security, and Replay and Recovery.