looplet

A Python loop for agents that call tools.

You provide the model, tools, task, and limits. Looplet checks each tool call, runs the tool, and records the result. It yields a Step after each call. Your code can inspect the result and stop before the next call.

Looplet also provides context management for longer runs and hooks to control each stage of the loop. Add only the features that your agent needs. Start in Python; use a cartridge when you need an agent stored and shared as files. The Quickstart runs one agent, checks its answer, saves its calls, and replays them.

A short loop is enough if it already meets your needs. Use Looplet when you need these controls without separate code for each agent. The loop stays visible, and your code still controls iteration.

Looplet requires Python 3.11 or newer. The core package has no third-party runtime dependencies. It does not require a workflow graph, a hosted service, or a cartridge.

Documentation | Quickstart | Python API

Run one loop

Install the published package for the Python examples and CLI commands in these guides. No local repository checkout is needed.

python -m pip install "looplet==0.4.0"

Run this inside a virtual environment; see Install. Installation needs network access, but not Git.

The example uses fixed model responses. It runs without a model service or an API key.

from contextlib import closing

from looplet import DefaultState, LoopConfig, MockLLMBackend, composable_loop, tool, tools_from


@tool(description="Find the team that owns a service.")
def lookup_owner(service: str) -> dict:
    owners = {"payments": "fintech-platform", "search": "discovery"}
    return {"service": service, "owner": owners.get(service)}


llm = MockLLMBackend([
    '{"tool":"lookup_owner","args":{"service":"payments"}}',
    '{"tool":"done","args":{"summary":"The payments owner is fintech-platform."}}',
])
tools = tools_from([lookup_owner], include_done=True, validate=True)
state = DefaultState(max_steps=2)

with closing(composable_loop(
    llm=llm,
    tools=tools,
    state=state,
    config=LoopConfig(max_steps=2, use_native_tools=False),
    task={"goal": "Find the payments owner, then finish."},
)) as steps:
    for step in steps:
        print(step.tool_call.tool, step.tool_result.data)

print(state.termination_reason)

The loop calls lookup_owner, then done. The lookup returns fintech-platform as the payments owner. The last line prints done, the stop reason.

Each yielded step follows a tool call. The tool has already run when your code receives that step. Use break to stop before the next call. closing closes the loop and runs its end hooks. Your code must close resources that it creates.

validate=True checks top-level argument types, nullability, and enum choices before tools run. Nested data and other constraints remain the tool's responsibility. Without this option, the base registry checks argument names and required fields, not full types.

This example selects the JSON-text protocol for its fixed responses. Real models use native tool calls by default. See Install for provider adapters and configuration.

The Quickstart adds a result helper, pytest checks, capture, and replay to this same agent. For async code, use async_composable_loop() with contextlib.aclosing.

Add only what you need

The same loop supports these optional features. You do not need a new execution engine to use them.

Looplet 0.4.0 includes the Python helpers and CLI commands used in these guides. Older commands, such as run-cartridge, describe, and show, remain supported.

Check results

A done step means that the loop accepted completion. It does not prove that the answer is correct.

Use a collector to read the files or records that the agent produced. Use a grader to compare that evidence with the expected result. Required graders can fail a test or a continuous integration check.

Run the regression example after installation:

looplet-proof

The example records fixed model responses and an incorrect report. It changes one tool line and replays the responses with the corrected tool. A collector reads the new report. The required grader changes from fail to pass. See the walkthrough for the files and limits.

Replay fixes model responses, not tool effects. Tools, networks, clocks, and random values can change unless your host controls them. A prompt or model change needs new model runs.

An agent's own tests are not protected acceptance checks. Keep release checks outside the code that a candidate can change. Run untrusted code in an isolated process or operating system environment.

Use it in an agent that you have

Keep your provider and tool functions. Replace the control loop first. Check that the new loop preserves the behavior you need. Then add capture, hooks, or result checks as needed.

See the Migration guide for the full procedure.

When Looplet fits

Use Looplet when:

• One model calls tools until the task ends.
• Your team uses Python, Git, and pytest.
• Your code must control when tools run.
• You need saved runs and tests for agent changes.

Use something else when:

• Your main task needs a durable workflow graph.
• You need a complete assistant, not a Python library.
• You need a managed dashboard as your main interface.
• A small loop that you wrote already meets your needs.

Looplet can run inside a workflow engine. It can export evidence to other systems. It does not replace those systems.

Documentation

See the documentation site for the full guide list.

Stability

Looplet follows semantic versioning. Before version 1.0, a minor release can change an API incompatibly. Pin the minor version for a published install:

looplet>=0.4,<0.5

The latest PyPI release is 0.4.0. It includes the examples and APIs in this guide. See the changelog and release plan.

Contributing

Report bugs or propose examples and backend adapters. A core feature must work across task domains. Include checks for the behavior that your change affects.

See CONTRIBUTING.md. Report security issues as described in SECURITY.md.

License

Apache License 2.0. See LICENSE.