Agents

Agents define role instructions, tools, provider metadata, and private context. Jobs execute under an agent.

Symbol	Import path	Purpose	Stability
`Agent`	`statek.agents.agent`	Base workflow and tool specification	Core
`SupervisedAgent`	`statek.agents.agent`	Base for queued or delegated agents	Core
`WarmupDef`	`statek.agents.agent`	Parsed warmup code and metadata	Core
`DialogAgent`	`statek.agents.dialog_agent`	One-to-one dialog agent with `send_message` integration	Specialized
`Reminder`, `RecurringReminder`	`statek.agents.dialog_agent`	Dialog reminder policies	Specialized
`Coordinator`	`statek.agents.coordinator`	Delegates requests to task agents	Specialized
`MessageDispatcher`	`statek.agents.message_dispatcher`	Routes incoming messages to threads	Specialized
`Researcher`	`statek.agents.researcher`	Research and answer agent template	Specialized

For practical reminder examples, see Harness Reminders.

`Agent`

@db0.memo
@dataclass
class Agent:
    role: str
    _system_prompt: Optional[SystemPrompt]
    _tools: list[Callable]
    _metadata: Optional[dict[str, str]] = None
    _description: Optional[str] = None

Defines the reusable role, prompt, tools, metadata, and context for jobs.

Import path: from statek.agents.agent import Agent

Parameters

Name	Description
`role`	Application-defined role name. Prompt files also match agents by role.
`_system_prompt`	Parsed `SystemPrompt` or `None` when prompt files will fill it.
`_tools`	Tool callables available to the agent. Names beginning with `_` become internal tools.
`_metadata`	Prompt/job metadata. `MODEL` is required before creating a `JobDef`.
`_description`	Optional short capability description.

Properties and methods

Member	Returns	Description
`description`	`str	None`
`context`	`dict	None`
`all_tools`	`list[Callable]`	Regular and internal tools, including name-resolved tools.
`system_prompt(task_difficulty, job_params=None, **kwargs)`	`str`	Formats the prompt for a difficulty and job parameters.
`update_system_prompt(new_prompt)`	`bool`	Updates only when content differs.
`update_metadata(new_metadata)`	`bool`	Updates metadata only when it differs.
`update_description(new_description)`	`bool`	Updates description only when it differs.
`init_context()`	`None`	Override hook for agent-specific context.
`get_adapter(name)`	`Any	None`
`append_tool(tool_or_name)`	`None`	Adds a callable or context-resolved tool name.
`get_examples()`	`list[str]`	Lists example names accessible to the role.

Raises

system_prompt(...) can raise formatting errors when prompt placeholders cannot be resolved. Tool formatting can raise ValueError if a name-based tool is missing from context.

from statek.agents.agent import Agent
from statek.prompt_config import make_system_prompt
 
agent = Agent(
    role="analyst",
    _system_prompt=make_system_prompt("Use the available tools.\n\n## Rules\n{tools}"),
    _tools=[],
    _metadata={"MODEL": "openai/gpt-5-mini"},
)

`SupervisedAgent`

@db0.memo
@dataclass
class SupervisedAgent(Agent):
    warmup_def: Optional[WarmupDef] = None

Adds warmup definitions and job-definition creation for agents managed by queues, coordinators, or subtasks.

Import path: from statek.agents.agent import SupervisedAgent

Member	Returns	Description
`referenced_locals`	`list[str]`	External local names referenced by warmup code.
`update_warmup_def(unparsed_warmup_def)`	`bool`	Parses and updates warmup code only when changed.
`create_job_def(tools=None, warmup_code=None, shared_vars=None, locale=None, **kwargs)`	`JobDef`	Creates a `JobDef` with combined warmup code and job parameters.

from statek.agents.agent import SupervisedAgent
from statek.prompt_config import make_system_prompt
 
agent = SupervisedAgent(
    role="worker",
    _system_prompt=make_system_prompt("Handle one queued task."),
    _tools=[],
    _metadata={"MODEL": "openai/gpt-5-mini"},
)
 
job_def = agent.create_job_def(task_id="A-42")

`WarmupDef`

@db0.memo
@dataclass
class WarmupDef:
    warmup_code: str | CodeBlock | Sequence[str | CodeBlock] | None = None
    metadata: dict[str, Any] | None = None

Stores warmup code parsed from configuration.

Import path: from statek.agents.agent import WarmupDef

Member	Returns	Description
`hidden`	`bool`	`True` when metadata contains `hidden=True`.

Specialized agents

Class	Signature	Description
`DialogAgent`	`DialogAgent(send_message, tools=None, role="dialog_agent", add_answer_tool=True, _metadata=None)`	Builds dialog tools around a `send_message(body, media=None)` callable. Temporal `send_message` callables are rejected.
`Coordinator`	`Coordinator(task_agents, role="coordinator")`	Exposes task-agent discovery and delegation tools.
`MessageDispatcher`	`MessageDispatcher(chat_history, start_new_thread, dispatch_to, role="message_dispatcher")`	Wraps routing callables as tools for thread dispatch.
`Researcher`	`Researcher(send_message=None, tools=None, role="researcher")`	Adds or reuses `ask` and `answer` tools.
`RecurringReminder`	`RecurringReminder(text, min_dialog_len=None)`	Fires after the configured dialog length, or immediately when length is not set.

RecursiveReminder remains available as a deprecated compatibility alias for RecurringReminder.

from statek.agents.researcher import Researcher
 
def send_message(body: str, media=None):
    print(body)
 
agent = Researcher(
    send_message=send_message,
    role="researcher",
)
agent.update_metadata({"MODEL": "openai/gpt-5-mini"})

Related APIs: Jobs, Tools, Prompts, Runners.

Overview Jobs