Skip to content

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.

from jaz import invoke
from 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")

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 invoke
from jaz.hooks import Hook
from jaz.hooks.events import LLMQueryEnter
from 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.

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.