Concepts
This page defines the handful of terms that JAZ’s docs, guides, and API reference lean on. If you have run the Quick start, you have already seen most of them — here they are spelled out, each with a tiny example where one helps.
What JAZ is
Section titled “What JAZ is”JAZ is an open-source Python framework for building LLM agents — programs powered by a
large language model (the kind behind ChatGPT, Claude, and so on). It is built on a single
primitive, invoke: a function whose body the model writes, as code, each time it is
called. The model’s response is that code — JAZ runs it, the agent observes the result,
and it iterates until it can return a result of the type you asked for. Everything the model
sees — the inputs you pass and its own running history — is a variable in that code.
That is the whole idea, and it is what sets JAZ apart from frameworks that ask the model for prose and then parse tool calls or code blocks out of it: in JAZ there is nothing to parse. The response is the program.
The REPL loop
Section titled “The REPL loop”Every agent runs a REPL loop (REPL = read–eval–print loop, like an interactive Python prompt). One turn of the loop is:
- The model writes a snippet of Python.
- JAZ runs it in a Python interpreter and captures the output.
- The agent observes the output (values, printed text, or an error).
- It writes more code to continue, returns a final value, or raises.
The loop repeats until the agent returns or hits a limit. Because the agent’s work is code, you can read, log, and reason about exactly what it did.
invoke
Section titled “invoke”invoke is the one function you call to run an agent. You give it a task; it returns the
agent’s result.
from jaz import invoke
result = invoke(task="Calculate the factorial of 10")print(result) # 3628800There is also an async version, ainvoke, with the same signature.
ReturnType and typed results
Section titled “ReturnType and typed results”By default invoke returns whatever the agent returns, typed as object. To get a result of
a specific type — and have JAZ enforce it — pass ReturnType(T) as the first positional
argument:
from jaz import invokefrom jaz.hooks import ReturnType
result = invoke(ReturnType(int), task="Calculate the factorial of 10")# result is guaranteed to be an intReturnType validates the type of the result, not its exact value — the task still runs
against a live model.
ReturnType is a hook, not an input. That is why it goes in
positionally rather than as a keyword argument: the hook itself never becomes a variable in the
agent’s REPL. What it does add, as inputs, is every class the agent would have to construct:
ReturnType(Report) or ReturnType(list[Report]) makes Report an input, exactly as if you had
passed Report=Report, so the agent can build one. Builtins such as str and list are
already there and are not added:
result = invoke(ReturnType(Report), task="...")You do not need to understand hooks to use it — just pass it first.
Inputs
Section titled “Inputs”Every keyword argument you pass to invoke becomes a variable inside the agent’s REPL,
under the same name, and is rendered into the agent’s prompt. It can be any Python object.
That is the whole input model.
In particular, JAZ has no notion of a “prompt”, a “tool” or a “data” argument. Nothing in
invoke distinguishes them, because nothing needs to: each one is an object bound to a name
and described to the model. The categories below are how people talk about inputs, not
anything the framework knows:
- A task (prompt / spec) — what you want done, in plain language. By convention it goes in
an input named
task, but the name is not special: you could call itquestion,instructions, or anything else. It is just a string bound to a name. - Tools — plain Python functions or objects the agent can call (see below).
- Data — the values the agent works over: numbers, strings, a DataFrame, whatever you pass.
A class is an input. A module is an input. Your own object is an input. They all arrive the same way.
result = invoke( ReturnType(list), task="Double each number in the list", numbers=[1, 2, 3, 4, 5],)print(result) # [2, 4, 6, 8, 10]Here the agent’s REPL starts with task and numbers already bound to your values.
How an input is described
Section titled “How an input is described”Being bound in the REPL is only half of it — the model also has to be told what it has. Each input is rendered into the prompt, and what gets rendered depends on the object:
| The input is… | The model is shown |
|---|---|
| a class | its docstring and public members |
any other callable — a function, a method, an object with __call__ |
its signature and docstring |
| a module | its summary and the names it exports |
an object that renders itself through neither __str__ nor __repr__ |
its class docstring and public attributes |
| anything else (the default) | its str() |
This is why a tool needs no schema: a function already carries its signature and docstring, so passing it is describing it. It is also how you change what the model is shown, with the Python you would write anyway:
- A docstring is what describes a function, a method or a class — write the one you would want a colleague to read.
- A
__str__(or__repr__) on a class makes its instances render as that text instead of as their docstring and attributes. Use it when an object has a better summary of itself — a short preview of a large dataset, say, rather than every member it carries. (A dataclass already has one: its generated__repr__. An object that also defines__call__is a callable, so it is shown by its signature and docstring instead.)
A tool is a capability you give the agent: a plain Python function or object, passed in as an input like any other. The agent reads its signature and docstring to learn how to call it — there is no special wrapper class to register.
def get_weather(city: str) -> str: """Return the current weather for a city.""" ...
result = invoke( task="What should I wear in Paris today?", get_weather=get_weather,)Inside its REPL the agent can now call get_weather(...) directly.
Recursive invoke
Section titled “Recursive invoke”An agent can call invoke again from inside its own code, spawning a nested agent (a
“subagent”). Those nested calls can nest further, forming a tree of agents that decompose,
search, or refine a problem. invoke is available inside the REPL automatically, so the agent
just calls it.
from jaz.hooks import ReturnType, RecursionLimit
with RecursionLimit(max_depth=3): # optional cap; recursion is unbounded by default result = invoke( ReturnType(list), task="For each item, use invoke to process it, then combine the results.", items=[1, 2, 3], )RecursionLimit(max_depth=...) caps how deep the tree may grow.
Inputs are local to the invoke you pass them to. They do not reach the subagents that
agent spawns:
invoke(task="...", get_weather=get_weather)# This agent can call get_weather(...).# Any subagent it spawns CANNOT — the name is not bound in the subagent's REPL.That is the problem scope solves. It binds values as ambient inputs: everything inside
the with block sees them, nested invokes included, all the way down the tree.
from jaz import invoke, scope
with scope(get_weather=get_weather): invoke(ReturnType(str), task="Plan a trip to Paris and Rome.") # This invoke and every sub-invoke beneath it can call get_weather(...).It is the same as passing get_weather=... to every invoke in the tree by hand — without
the hand-threading. This is the usual way to give an agent tools, since most real tools should
be available to the whole subtree rather than to the top-level call alone.
A few rules worth knowing:
- Keyword arguments only, and the names must be valid Python identifiers — they become
variables in the REPL. Splat a dynamic mapping with
scope(**tools). - An inner scope shadows an outer one with the same name, and the outer value is restored
on exit, exactly like any
withblock. - Passing a scoped name again as an
invokekwarg raises. To give one call a different value, nest anotherscopearound it rather than re-passing the kwarg. - Names can be shadowed but not removed — there is no way to unbind a name for a block.
Hooks, events, and effects
Section titled “Hooks, events, and effects”Hooks are JAZ’s extension mechanism. A hook observes the agent as it runs — through
events (things that happen, such as “about to query the LLM” or “a turn finished”) — and
can influence it by returning effects (changes to apply, such as adding a message).
Many of JAZ’s built-in features are hooks, including ReturnType, ValidateReturn,
BudgetPool, RecursionLimit, IterationLimit, PrintLogger, and FileLogger.
A hook applies either to a single call — pass it positionally, like ReturnType — or, using
the same scoping idea as above, to a whole subtree by activating it with with:
from jaz.hooks import FileLogger
with FileLogger("agent.log"): invoke(ReturnType(str), task="...") # logs this invoke and everything it nestsFor example, BudgetPool is the hook that caps effort across a tree: while it is active it
tracks total LLM cost (USD) and call count, shared across the whole invoke tree.
from jaz.hooks import BudgetPool
with BudgetPool(cost_budget=0.50, calls_budget=100): invoke(ReturnType(str), task="Complex task")See the Hooks guide to write your own, and Budgets & configuration for the per-level limits.
The interaction protocol
Section titled “The interaction protocol”The interaction protocol is the codec that translates between the LLM’s responses and the
REPL’s code execution — you rarely touch it directly, but it is one of the three things you can
configure (jaz.configure(llm=..., repl=..., protocol=...)), alongside the LLM backend and the
REPL.
Where to go next
Section titled “Where to go next”- Quick start — run your first agent.
- Recursive agents, Budgets & configuration, and Hooks — go deeper.
- Tutorials — learn by running notebooks in Colab.