STATEK
Examples Machinery

STATEK Examples Machinery

STATEK examples are reusable code-and-output transcripts that an agent can inspect before it writes its own Python.

They are not generic documentation examples. They are part of the runtime context machinery: applications store example files on disk, STATEK loads examples for the current agent, and system tools can print selected examples into the job history.

⚠️

Treat examples like executable prompt material. They can strongly influence what code an agent writes, so keep them reviewed, current, and free of secrets, credentials, customer-private payloads, and broad operational assumptions.

Directory Layout

Configure the example root with STATEK_EXAMPLES_DIR or StatekSettings.examples_dir:

STATEK_EXAMPLES_DIR=./examples

Examples are grouped by agent role. The current agent's role maps to a subdirectory:

examples/
  dispatcher/
    001-route-request.md
    002-continue-thread.md
  report_writer/
    001-summarize-report.md

For an agent with role="report_writer", list_of_examples() reads from:

<examples_dir>/report_writer/

Files are loaded recursively from that agent directory. Only Markdown files ending in .md are parsed.

Example File Format

An example file contains optional metadata headers followed by alternating Python code and console output.

Summarize One Report
# seq_id: 0
# name: Summarize one report
# difficulty: low
 
```python
print("Request:", request_text)
```
Request: Summarize the latest report.
# ----------
```python
report = load_report(report_id)
summary = summarize_report(report)
print(summary)
```
The report is ready for review.

Metadata lines use # key: value before the content. Common keys:

  • seq_id: numeric sort key; examples with seq_id appear before examples without one
  • name: human-readable label shown by list_of_examples()
  • difficulty: optional task difficulty metadata used by difficulty-aware flows

The # ---------- separator splits startup context from the main example:

  • content before the separator becomes warmup_items
  • content after the separator becomes example_items
  • without the separator, all content becomes example_items

Console output can be written as plain text after a fenced Python block. In console-style examples, lines prefixed with > are parsed as console output.

Listing Examples

Inside an active STATEK job, agents use the wrapper tools from statek.agents.agent:

List Available Examples
list_of_examples()
list_of_examples(start_index=10, limit=5)

list_of_examples() prints a numbered list:

# Example ID: Example name (2 total)
0: Summarize one report
1: Ask for missing information

Those numbers are the example IDs used by show_example(...). If no examples directory is configured, or the current agent has no example directory, STATEK prints:

# No examples found

Application code can inspect the same names through an Agent instance:

Inspect Example Names
example_names = report_writer.get_examples()

The returned list uses the same order and indexes as list_of_examples().

Showing an Example

Use show_example(...) to print an example into the job context:

Show an Example by ID
show_example(0)

If no ID is passed, STATEK looks for default_example_id in the job's local context:

Show the Default Example
default_example_id = 0
show_example()

That pattern is useful when a dispatcher or parent job has already selected the most relevant example and passed the ID through dynamic warmup.

After a successful lookup, STATEK stores the selected ID in persistent context as last_example_id. Failed lookups do not overwrite the previous value.

If the ID is missing, invalid, or out of range, STATEK prints an example-not-found message instead of raising a normal application error.

Warmup Integration

Examples are often loaded during warmup so the first model step sees the relevant transcript:

Load Examples During Warmup
list_of_examples() #STATEK: as tool
# ----------
show_example(default_example_id) #STATEK: as tool

The #STATEK: as tool annotation records the call and result as a structured tool-call warmup entry rather than just raw console output. See Warmup Code for block syntax and tool-call warmup behavior.

Keep warmup examples focused. Printing every available example can bury the actual request and make the next model step less reliable.

Formatting

show_example(...) formats output with:

  1. STATEK_EXAMPLES_STYLE, when set
  2. otherwise the active STATEK_CHAT_STYLE
STATEK_CHAT_STYLE=DIRECT
STATEK_EXAMPLES_STYLE=MARKDOWN

Supported styles follow the same chat-style concepts used elsewhere in STATEK. For example:

  • MARKDOWN uses fenced Python blocks
  • CONSOLE uses plain code with > -prefixed console output
  • MD_DIALOG wraps console output in <CONSOLE> tags

When STATEK_XML_BOX_EXAMPLE is set, show_example(...) wraps the entire formatted example in that XML tag:

STATEK_XML_BOX_EXAMPLE=EXAMPLE

Without XML boxing, show_example(...) prints comment markers:

# --- EXAMPLE: Summarize one report ---
...
# --- END OF EXAMPLE ---

See Chat Styles for the broader formatting model.

Difficulty Metadata

Example metadata can include a difficulty value:

Set Example Difficulty
# difficulty: medium

STATEK parses common difficulty metadata keys such as difficulty, DIFFICULTY, TASK_DIFFICULTY, and task_difficulty. When a flow uses dynamic difficulty, a shown example can help select prompt sections and model mappings appropriate for that difficulty.

Keep difficulty labels conservative. They are routing and prompt-selection hints, not quality guarantees.

Creating Examples From Jobs

STATEK also has lower-level helpers for building and parsing example objects:

Extract an Example From a Job
from statek.executors.example import extract_example, format_example
 
example = extract_example(job, name="Summarize one report")
markdown = format_example(example, chat_style)

extract_example(...) reads a completed or inspected job and captures:

  • metadata such as name, model, model family, turn count, exception count, exit status, agent role, and job params when available
  • warmup code and warmup console output
  • LLM response code and console output for each turn

Other helpers include:

  • parse_example(...): parse one Markdown example into an Example
  • load_examples(...): load all .md examples from a directory and sort by seq_id
  • format_example(...): render an Example using a chat style

These helpers are useful for tooling and tests. Most agent workflows should use list_of_examples(), show_example(...), and Agent.get_examples().

Practical Rules

Use examples for behavior that is easier to demonstrate than explain:

  • how to inspect available context
  • which application tools to call first
  • how to handle common missing-information cases
  • how to produce the expected final answer shape
  • how to avoid known bad tool sequences

Do not use examples as hidden policy. The agent prompt, tool docstrings, permissions, and application checks still need to state the actual rules.

Where to Go Next

Read Documents Machinery for document libraries, Warmup Code for loading examples before the first model step, Prompt Definitions for difficulty and tool-scope metadata, and Practical Examples for application-shaped dispatcher and worker patterns.

Replay and RecoveryDocuments Machinery