Hooks
Hooks are JAZ’s extension mechanism. A hook observes agent execution through events
(things that happen as the agent runs, e.g. “about to query the LLM”) and influences it by
returning effects (changes to apply, e.g. “add this message”). You’ve already used hooks:
ReturnType, BudgetPool, and RecursionLimit are all built-in hooks. They can be passed
positionally to a single invoke or activated as a with block that propagates to nested
invoke calls — see the two ways to pass a hook, and
Concepts for the event/effect model.
Built-in hooks
Section titled “Built-in hooks”from jaz import invokefrom jaz.hooks import ReturnType, FileLogger, BudgetPool
with FileLogger("agent.log"), BudgetPool(cost_budget=1.0): result = invoke(ReturnType(str), task="Build a web scraper")| Hook | Purpose |
|---|---|
ReturnType |
Declare + enforce the invoke’s return type |
ValidateReturn / ValidateREPLCode |
Validate the return value / veto REPL code before it runs |
BudgetPool |
Shared LLM cost / call-count budget with hard-stop enforcement |
IterationLimit / RecursionLimit |
Per-level turn cap / invoke-nesting cap |
BudgetForcing |
Refuse early finishes so the agent keeps working |
ContextWindowWarning |
Warn the agent as its prompt nears the model’s window |
PrintLogger / FileLogger |
Log events to console / file |
RolloutRecorder |
Record the run’s turns in a training-ready format |
TrajectoryRecorder / TrajectoryReplay |
Write / resume a run as an ATIF trajectory |
JaegerTracing / LangfuseTracing |
OpenTelemetry tracing presets (export traces to Jaeger / Langfuse) |
The first few rows cover everyday use; the rest (BudgetForcing and below) are advanced or
optional — reach for them only when you need them, and see the
Hooks reference for details.
Hooks compose naturally as context managers — stack as many as you need:
with FileLogger("agent.log"), BudgetPool(cost_budget=1.0): result = invoke(ReturnType(str), task="Build a web scraper")Writing a custom hook
Section titled “Writing a custom hook”Subclass Hook and override the typed handler for the event you care about — no
isinstance dispatch. Events come from jaz.hooks.events and effects from
jaz.hooks.effects:
from jaz import invokefrom jaz.hooks import Hookfrom jaz.hooks.events import LLMQueryEnterfrom jaz.hooks.effects import AddMessages, Effect
class ConciseHook(Hook): """Instruct the agent to be concise after iteration 3."""
def on_llm_query_enter(self, event: LLMQueryEnter) -> list[Effect]: if event.iteration >= 3: # iterations are 0-based return [AddMessages([{"role": "user", "content": "Be concise."}])] return []
# Hooks activate via context managers and propagate to nested invoke() calls.with ConciseHook(): result = invoke(task="Solve this step by step")A hook that wants every event (rather than one) overrides on_any instead, which runs in
addition to the matched handler.
See the Hooks reference for the events and effects, and the
generated jaz.hooks pages for per-symbol detail.
Tracing quick start
Section titled “Tracing quick start”from jaz.hooks import ReturnType, LangfuseTracing
with LangfuseTracing(): result = invoke(ReturnType(int), task="Calculate 2+2")Set LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and optionally LANGFUSE_HOST.