Client API

StatekClientAPI exposes job-submission methods intended for external processes and clients. It is designed to work with optional db0-rpc: the submission methods are decorated with @rpc.remote, so a db0-rpc-enabled deployment can expose them remotely while local calls keep the same Python API.

The high-level worker startup path, start_statek_async(...), instantiates StatekClientAPI() while preparing the STATEK process. That makes the API object available in the worker process before the agentic loop starts.

If db0_rpc is not installed, STATEK loads a no-op RPC adapter. In that mode the methods are ordinary local Python methods; remote exposure requires db0-rpc integration in the hosting application.

Symbol	Import path	Purpose	Stability
`StatekClientAPI`	`statek.statek_client_api`	Singleton client-facing API for creating STATEK jobs	Provisional external API
`submit_new_job`	`StatekClientAPI` method	Create one job for a supervised agent	Provisional external API
`submit_new_jobs_batch`	`StatekClientAPI` method	Create multiple jobs for a supervised agent	Provisional external API

`StatekClientAPI`

@db0.memo(singleton=True)
class StatekClientAPI:
    """Client API for creating STATEK jobs from external processes."""

Creates jobs through the same lower-level helpers used by in-process STATEK code, but with a small API surface suitable for clients that already have access to persisted agent objects.

Import path: from statek.statek_client_api import StatekClientAPI

Notes

Topic	Detail
Agent type	Methods expect a `SupervisedAgent`.
RPC decoration	Public methods are decorated with `@rpc.remote`.
RPC dependency	`db0_rpc` is optional. Without it, the remote decorator is a no-op.
Execution	Submitted jobs are created in persisted STATEK state. A worker loop such as `start_statek(...)` or `run_jobs_loop(...)` still needs to run them.
Root export	`StatekClientAPI` is not exported from `statek.__all__`; import it from `statek.statek_client_api`.

from statek.statek_client_api import StatekClientAPI
 
api = StatekClientAPI()

`submit_new_job`

def submit_new_job(
    self,
    agent: SupervisedAgent,
    shared_vars: dict[str, Any] | None = None,
    locale: StatekLocale | str | None = None,
    **kwargs,
) -> Job

Creates one new STATEK job for the given supervised agent.

Parameters

Name	Description
`agent`	The target `SupervisedAgent`.
`shared_vars`	Optional mapping of local variable names to objects that should be available in the job.
`locale`	Optional `StatekLocale` or locale string such as `"PL-PL"`. Strings are resolved with `resolve_locale(...)` before job creation.
`**kwargs`	Agent-specific job parameters passed to the job definition.

Returns: the newly created Job.

Errors: locale string parsing can raise errors from resolve_locale(...). Job creation can raise errors from the underlying create_new_job(...) path, including invalid agent metadata.

See Locale Selection for how locale affects system prompts, user-message hints, and child-job inheritance.

from statek.statek_client_api import StatekClientAPI
 
job = StatekClientAPI().submit_new_job(
    agent=dispatcher,
    shared_vars={"event": incoming_event},
    locale="EN-US",
    source="webhook",
)

`submit_new_jobs_batch`

def submit_new_jobs_batch(
    self,
    agent: SupervisedAgent,
    shared_vars_batch: list[dict[str, Any] | None],
    locale: StatekLocale | str | None = None,
    **kwargs,
) -> list[Job]

Creates multiple STATEK jobs for the same supervised agent. Each item in shared_vars_batch becomes the shared variable mapping for one job. locale and **kwargs are shared across the batch.

Parameters

Name	Description
`agent`	The target `SupervisedAgent`.
`shared_vars_batch`	A list of `shared_vars` entries, one per job. Entries may be `None`.
`locale`	Optional `StatekLocale` or locale string such as `"ES-ES"`.
`**kwargs`	Agent-specific job parameters applied to every job in the batch.

Returns: a list of newly created Job objects.

from statek.statek_client_api import StatekClientAPI
 
jobs = StatekClientAPI().submit_new_jobs_batch(
    agent=dispatcher,
    shared_vars_batch=[
        {"event": first_event},
        {"event": second_event},
    ],
    locale="EN-US",
    source="batch_import",
)

db0-rpc use

StatekClientAPI does not start an RPC server by itself. It provides methods that db0-rpc can expose when the host application configures db0-rpc and opens the relevant dbzero state.

from statek.rpc_integration import has_rpc
from statek.statek_client_api import StatekClientAPI
 
api = StatekClientAPI()
 
if has_rpc():
    # The host application's db0-rpc setup can expose api.submit_new_job
    # and api.submit_new_jobs_batch as remote methods.
    pass

Related APIs: Runners, Operations, Agents, Jobs, Settings.

Runners Examples and Documents