You can use the {context} variable to inject contextual information:

- Ticket: TICKET-7
- Date: 2026-05-06
- Working directory: /Users/caro
- Platform: darwin 25.1.0
- Turns remaining: 8
- Input tokens remaining: 95000
- Output tokens remaining: 12000
- Time remaining: 240s

Every value is a variable of its own: {ticket}, {date}, {dir}, {platform}, {os_version}, {turns_remaining}, {input_tokens_remaining}, {output_tokens_remaining}, and {time_remaining}.

See more: AgentBuilder.

You can also read the model or provider individually: .provider(Provider.from_env()) or .model(Model.from_env()).

You can configure models to set a custom context window size or the applied reasoning. Claude, GPT, Mistral, and Qwen families are pre-configured.

Configure a custom model:

from agentwerk import Agent, Model

agent = Agent().model(
    Model("my-local-model").context_window(128_000).reasoning_effort("high")
)

See Provider and Model.

See TicketQueue.

Terms

Fields

Rules

• =, !=, IN, and NOT IN compare exactly, ~ and !~ ignore case.
• IS EMPTY and IS NOT EMPTY read label, agent, parent, result, started, finished, and failed only.
• ~ and !~ read task and result only.
• A field holds one value per ticket, so label = a AND label = b is rejected and names IN as the fix.
• ORDER BY names one field and closes the query. Every field sorts, key by its number and status along the lifecycle.
• Without it tickets arrive in creation order, which is also what breaks a tie and what a callable answers in. A ticket missing the field sorts last.
• The four times sort and nothing else, since AQL has no >. The three an agent can leave unset also read IS EMPTY, so finished IS EMPTY selects the tickets still open.
• A query may be nothing but an ORDER BY, which selects every ticket.
• A string that does not compile raises ValueError, as does Query(query), which compiles one without running it.

Every method that takes a query also takes a callable, for a condition no field carries:

tickets.find_tickets(lambda t: len(t.replies) > 4)

Ticket members:

See Ticket.

1. Create tickets

A handover can be performed through a single finish tool call:

{
  "handover": "report",
  "result": "Three products lead on value.",
  "task": "Write the board report from {parent_key}."
}

When task is not defined, the child ticket's body is the result itself. A task populates template variables:

• {parent_key}: the key of the ticket that was handed over.
• {parent_result}: its result.
• {parent_result_path}: the path of its result file.

2. Read tickets

The tickets tool reads what any finished ticket produced, by key:

{ "action": "result", "key": "TICKET-1" }

3. Read result file

The read_file tool reads the original result file when its path is known:

{ "path": ".agentwerk/tickets/TICKET-1/result.json" }

4. Share knowledge

The knowledge tool allows sharing knowledge with other agents:

{
  "action": "write",
  "slug": "value-ranking",
  "description": "How the products rank on value.",
  "content": "Three products lead on value: ..."
}

5. Register hooks

Use hooks to create new tickets when certain results arrived:

def hand_to_report(work, done, result):
    if done.has_label("research"):
        work.ticket(Ticket(result, label="report"))


tickets.on_result(hand_to_report)

A SchemaStore enforces schemas for all tickets with a certain label. Registering schemas centrally spares agents from passing complex schema structures during ticket creation (see TicketsTool) and handovers (see FinishTool):

from agentwerk import SchemaStore

schemas = SchemaStore()
schemas.label(
    "report",
    {
        "type": "object",
        "properties": {"title": {"type": "string"}},
        "required": ["title"],
    },
)

tickets.schemas(schemas)

See Schema and SchemaStore.

config(config) replaces the whole configuration, and get_config() reads it back. A violated limit emits a config_violated event, see EventKind.

The function returns a directive template. So you can access template variables, like {detail}, {attempt}, and {path}.

See prompts/directives for the built-in text.

.agentwerk/
├── events.jsonl                          every event (one per line)
├── tickets/
│   └── TICKET-1/
│       ├── ticket.json                   the ticket without its messages (key, status, label, timestamps)
│       ├── result.json                   the result the agent produced
│       ├── replies.jsonl                 every message exchanged with the model, one per line
│       └── outputs/<tool_use_id>.txt     full tool outputs spilled out of the messages
└── knowledge/
    ├── pages/<slug>.md                   knowledge pages
    └── index.md                          knowledge index

FinishTool and KnowledgeTool

FinishTool() and KnowledgeTool(store) are special tools, registered automatically on every agent. They are used for interacting with the TicketQueue or knowledge base. An interactive agent is the exception: it gets no FinishTool(), so it pauses for the next reply instead of ending its ticket.

CommandTool

The CommandTool allows you to granularly define what commands are allowed and what commands are denied.

git = (
    CommandTool("git")
    .allow("git status")
    .allow("git log *")
    .deny("git push*")
    .deny_flag("--force")
)

With an allow_flag set, a command carrying any other flag is refused:

cargo = CommandTool("cargo").allow("cargo test*").allow_flag("--all-features")

FetchUrlTool

The FetchUrlTool fetches a URL and returns its text, requesting it with the user agent agentwerk/<version>. impersonate() swaps in the headers and HTTP/2 settings a browser sends.

web = FetchUrlTool().impersonate()

Custom Tools

You can define custom tools for specific needs with the following parameters:

Describe the tool, then hand it the code it runs:

from agentwerk import tool


@tool(
    concurrent=True,
    schema={
        "type": "object",
        "properties": {"name": {"type": "string"}},
        "required": ["name"],
    },
)
def greet(name: str) -> str:
    """Say hello."""
    return f"Hello, {name}!"

See Tool.

Every event is written to the session log. You read events from the ticket queue, or from the session directory in .agentwerk/events.jsonl:

See EventKind and TicketQueue.

Save replies of every finished ticket as a training example:

def capture(work, event, ticket):
    if event.kind == "ticket_finished":
        model = work.model_for_agent(event.agent_id)
        Trajectory.from_ticket(event.agent_id, model, ticket).save("datasets")


tickets.on_ticket(capture)

Async handlers

on_result is blocking and prevents an agent continuing its work till the hook is finished. If you perform time-consuming operations use on_result_async instead: storing results in a database, posting them to an HTTP API, or uploading them to object storage. It takes an async def and runs it on the event loop you await finish on.

async def store(work, ticket, result):
    await database.insert(ticket.key, result)


tickets.on_result_async(store)

See TicketQueue.

Programmatically create entries:

from agentwerk import Page

store.pages().save(
    Page(
        "build-command",
        "How the project is built.",
        "Run `make` to compile.",
        tags=["build"],
    )
)

page = store.pages().load("build-command")
store.pages().remove("build-command")

See Knowledge.