Skip to content

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.

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.

Every agent runs a REPL loop (REPL = read–eval–print loop, like an interactive Python prompt). One turn of the loop is:

  1. The model writes a snippet of Python.
  2. JAZ runs it in a Python interpreter and captures the output.
  3. The agent observes the output (values, printed text, or an error).
  4. 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 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) # 3628800

There is also an async version, ainvoke, with the same signature.

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 invoke
from jaz.hooks import ReturnType
result = invoke(ReturnType(int), task="Calculate the factorial of 10")
# result is guaranteed to be an int

ReturnType 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.

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 it question, 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.

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.

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 with block.
  • Passing a scoped name again as an invoke kwarg raises. To give one call a different value, nest another scope around 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 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 nests

For 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 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.