Skip to content

How JAZ works

How it works

What happens inside invoke

You call it with a task and the Python you have in hand. The model writes the body of that call as Python code, JAZ runs it in a sandboxed interpreter, and the result comes back as a real Python value of the type you asked for. There is no graph to wire, no tool schema to write and nothing to parse: the model's reply is the program. Scroll to watch one call run, as described in the paper.

penguins.ipynbinvoke frame

The LLM writes each invoke's body; JAZ runs it

You writedef web_search(query: str) -> list[str]:    """Search the web; return result summaries."""    return parse_hits(SESSION.get(search_url(query))) plots = jaz.def invoke(LLM sees    task="Make plots comparing penguin species.",        Make plots comparing penguin species.    df=pd.read_csv("penguins.csv"),            species     island  ...  body_mass_g     sex        0    Adelie  Torgersen  ...       3750.0    MALE        1    Adelie  Torgersen  ...       3800.0  FEMALE        [344 rows x 7 columns]    web_search=web_search,        `web_search(query: str) -> list[str]`:        Search the web; return result summaries.): LLM writesprint(web_search(task))LLM sees['Palmer penguins in seaborn: Compare species ...', ...] LLM writesplots = []    for col in ["island", "body_mass_g", ...]:        plot = invoke(            subtask=f"Plot {col} by species",            df=df,            instructions=__history__[0].repl_output,        )        plots.append(plot)     return plotsplots
You get

Minimalist interface

Every input — a prompt, your data, a tool — is the same thing: a keyword argument with a name of your choosing.

Maximal expressivity

All inputs are available as variables.

Recursive subagents are available by default.

The REPL history itself is available as a variable in the REPL.

Return any Python object created in the REPL.

Make it yours

Small core. Your kind of agent.

The result type, the budget, and the tools the agent can use are all explicit in your code. Tick a feature: the lines it costs appear, and the output under the program changes with them. Copy it and run it — no new agent class required. New to agents that write code? Start here.

Add a feature
penguins.py
imports and configuration, and search_wikipedia's helpersincluded when you copy
from jaz import configure, invokefrom jaz.llm import LiteLLMimport pandas as pdimport requestsfrom urllib.parse import urlencodefrom dataclasses import dataclassfrom jaz.hooks import ReturnTypefrom jaz.hooks import BudgetPoolfrom jaz.hooks import IterationLimit, RecursionLimitfrom jaz.hooks import FileLogger # reads OPENAI_API_KEYconfigure(llm=LiteLLM(model="openai/gpt-5.4"))
# Wikipedia refuses requests' default User-Agent (HTTP 403).
SESSION = requests.Session()
SESSION.headers["User-Agent"] = (
    "jaz-example (https://jaz-lang.ai)")


def search_url(query: str) -> str:
    """The search, with each hit's title and lead."""
    params = urlencode({
        "action": "query", "format": "json",
        "formatversion": 2, "generator": "search",
        "gsrsearch": query, "prop": "extracts",
        "exintro": 1, "exsentences": 3,
        "exlimit": "max", "explaintext": 1,
    })
    return f"https://en.wikipedia.org/w/api.php?{params}"


def parse_hits(response: requests.Response) -> list[str]:
    """One "Title: lead" string per hit, in rank order."""
    response.raise_for_status()
    data = response.json()
    if "error" in data:
        raise RuntimeError(data["error"]["info"])
    pages = data.get("query", {}).get("pages", [])
    pages.sort(key=lambda p: p["index"])
    return [f"{p['title']}: {p.get('extract', '')}"
            for p in pages]
# seaborn's Palmer Penguins: 344 birds, 3 speciesPENGUINS = (    "https://raw.githubusercontent.com"    "/mwaskom/seaborn-data/master/penguins.csv") # a tool: any function; the agent reads its docstringdef search_wikipedia(query: str) -> list[str]:    """Search Wikipedia; return article summaries."""    return parse_hits(SESSION.get(search_url(query))) # the shape of the answer: a class, checked on return@dataclassclass SpeciesReport:    best_features: list[str]    summary: str # hooks see every event; the caps can stop the runwith (    # $0.50 or 100 LLM calls, across nested agents    BudgetPool(cost_budget=0.50, calls_budget=100),    # 10 turns per agent, at most 2 levels of agents    IterationLimit(max_iterations=10),    RecursionLimit(max_depth=2),    # every event, from every nested agent, to a file    FileLogger("agent.log"),):    # the agent writes and runs Python until it returns    report = invoke(        ReturnType(SpeciesReport),  # or it retries        task="How to tell apart different penguin species?",        df=pd.read_csv(PENGUINS),  # a live DataFrame        search_wikipedia=search_wikipedia,  # agent may call    )print(report)

Outputwhat print(report) shows — an example; yours will differ

Look at the head. Adélie penguins have a white ring around each eye, chinstraps a thin black line under the chin, and gentoos a white patch above each eye and an orange bill. Gentoos are also the largest of the three.In this data, size separates Gentoo first: flippers average 217 mm and body mass 5076 g, against 190–196 mm and about 3700 g for Adelie and Chinstrap. Bill length then splits those two: 48.8 mm for Chinstrap, 38.8 mm for Adelie. Island is a shortcut, too: every Gentoo is on Biscoe and every Chinstrap on Dream.Wikipedia: the chinstrap is named for the narrow black band under its head, which makes it look as if it is wearing a black helmet; the gentoo, its closest relative, is known for a loud trumpeting call made with the head thrown back; the Adélie is the most widespread penguin in the Antarctic, found along the entire coast.Size first: in this data Gentoo average 217 mm flippers and 5076 g, against 190–196 mm and about 3700 g for Adelie and Chinstrap, and bill length then splits Chinstrap (48.8 mm) from Adelie (38.8 mm). In the field, Wikipedia gives the chinstrap's narrow black band under the head, and the Adélie's range along the entire Antarctic coast.SpeciesReport(best_features=['eye ring', 'chin band', 'bill colour'], summary='Adélie have a white ring around each eye, chinstraps a thin black line under the chin, gentoos a white patch above each eye and an orange bill.')SpeciesReport(best_features=['flipper_length_mm', 'body_mass_g', 'bill_length_mm'], summary='Flipper length and body mass separate Gentoo (217 mm, 5076 g) from Adelie and Chinstrap (190–196 mm, about 3700 g); bill length then splits Chinstrap (48.8 mm) from Adelie (38.8 mm).')SpeciesReport(best_features=['head band', 'call', 'range'], summary='Wikipedia: the chinstrap has a narrow black band under its head; the gentoo a loud trumpeting call; the Adélie the widest range, along the entire Antarctic coast.')SpeciesReport(best_features=['flipper_length_mm', 'body_mass_g', 'bill_length_mm'], summary='In the data, flipper length and body mass separate Gentoo (217 mm, 5076 g) from the other two, and bill length splits Chinstrap (48.8 mm) from Adelie (38.8 mm); in the field, Wikipedia gives the chinstrap its black band under the head.')

agent.loga new file, one line per event, nested agents included

2026-10-12 09:12:04 [Agent] invoke enter: inputs={'task': 'How to tell apart…'}, depth=1, hooks=[…]
2026-10-12 09:12:04 [LLM] query enter: model=openai/gpt-5.4, messages=2 messages
2026-10-12 09:12:07 [LLM] query exit: model=openai/gpt-5.4, cost=$0.0138
2026-10-12 09:12:07 [Agent] repl exec 0 input: code='…', depth=1

Same output. The run stayed under $0.50 and 100 calls, so the cap never acted. Past either, invoke raises BudgetPoolExhaustedError instead of returning — and nested agents draw on the same pool.

Same output. The agent returned within 10 turns and never went two agents deep. Past either, invoke raises IterationLimitExhaustedError or RecursionLimitError.

no line for the steps: the agent works out what the task needs and writes the control flow itself, as code

Less wiring, more Python

Same task. See the difference.

Choose a use case and a framework. See how JAZ keeps your objects, tools, and return types in one ordinary Python call.

Choose an agent framework comparison
Use case
Compare JAZ with

Turn the same signups dict into a saved matplotlib bar chart.

Shared input — included when you copy either example
Shared Python setup
from matplotlib.figure import Figure

signups = {"Jan": 120, "Feb": 150, "Mar": 90}

JAZ
In
signups, the dict
Out
a Figure, checked by ReturnType
from jaz import configure, invoke
from jaz.hooks import ReturnType
from jaz.llm import LiteLLM

configure(llm=LiteLLM(model="openai/gpt-5-mini"))

fig = invoke(
    ReturnType(Figure),
    task="Plot signups per month as a bar chart titled 'Signups'.",
    signups=signups,
)
fig.savefig("signups.png")

Outputan example run; yours will differ

>>> fig
<Figure size 640x480 with 1 Axes>

signups.png written to disk

The result is the Figure itself, checked to be one. The agent wrote the plotting code against your data, so a different chart tomorrow needs no new tool.

pip install jaz-lang matplotlib

JAZ source ↗
LangChain
In
the dict, pasted into the prompt, and plot, a tool
Out
the last message's text; a PNG plot wrote
from langchain.agents import create_agent

def plot(kind: str, labels: list[str], values: list[float],
         title: str, path: str) -> str:
    """Save a "bar" or "line" chart of values by label to path."""
    fig = Figure()
    ax = fig.subplots()
    draw = {"bar": ax.bar, "line": ax.plot}[kind]
    draw(labels, values)
    ax.set_title(title)
    fig.savefig(path)
    return path

agent = create_agent(
    model="openai:gpt-5-mini",
    tools=[plot],
)
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": f"Plot signups per month as a bar chart titled 'Signups'.\n{signups}",
    }],
})
print(result["messages"][-1].content)

Outputan example run; yours will differ

Saved the bar chart 'Signups' to signups.png.

A general chart tool: the agent picks the kind and the title and reads the values out of the data. What it can draw is what the tool draws.

pip install langchain langchain-openai matplotlib

LangChain docs ↗