Bare Agent

Own the loop, not the framework.

A framework-free agent runtime you can read, run, and leave — a small library you
import and call, plus a visual studio that ejects to plain Python with zero dependency on us.

Why stateless? • Features • Quickstart • Studio • How it works • Eject • Configuration • Development

Most agent frameworks own your main(), hide control flow behind metaclasses and DAG executors, and obscure the actual prompts. bare-agent is the opposite: a small library — the agent loop, a tool registry, a 3-axis budget, and a LiteLLM gateway, ~600 readable lines — that you import and call. You own the loop. Every prompt is in plain sight. You can always eject to plain Python and run it with zero bare_agent dependency.

On top of the library sits an optional visual studio: wire agents into a chain on a canvas, attach tools, Run and watch tokens stream live, then eject the whole flow to a self-contained agent.py. Local-first — it runs at zero cost on Ollama; OpenAI, Anthropic, and Gemini are optional drop-ins through the same loop.

Built on Python 3.12 · LiteLLM · FastAPI · Next.js 16 — with no agent framework (no LangChain/LangGraph).

The studio, end to end: chain a Solver and an Explainer, attach the calculator, Run and watch each agent stream its turns, tool calls, and tokens live — with real per-call cost attribution (here on gpt-5.4-mini, ~$0.0006 for the whole chain) — then Eject to Python, a self-contained agent.py with zero bare_agent dependency. The same loop runs local-first on Ollama at $0.

Why stateless?

The agent loop is a stateless reducer over an explicit messages: list[dict]. This is the most important design decision in the library, and it was made deliberately. Here is what it costs (nothing) and what it pays (three things):

The cost: you pass the messages list explicitly. There is no magic session object accumulating state behind the scenes.

What you get for free:

1. Testability without a live LLM

Feed a canned messages list and a fake CompletionClient — assert on the result. Every one of the 29 tests runs hermetically: no Ollama daemon, no Redis, no LLM API key required. The test suite is a CI gate, not a flaky integration smoke.

# How the test suite works — no real LLM
agent = AgentLoop(
    registry=registry,
    llm=FakeCompletionClient(responses=["The answer is 42."]),
    budget=Budget(max_turns=3),
    system_prompt="You are a test agent.",
)
result = await agent.run("What is 6 × 7?")
assert result.answer == "The answer is 42."
assert result.stop_reason == "completed"

2. Durability for free

The messages list is a plain Python list of dicts — JSON-serializable by construction. Checkpoint it to Postgres (or a file) after each turn. If the process crashes, deserialize and resume from the last checkpointed step. No workflow engine required. This is the same pattern that Argus uses for DBOS durable execution.

3. Eject-to-code is honest

"Eject to plain Python" works because the list is the program — there was never a framework underneath to lift out. The compiled agent.py is not a snapshot of framework state; it is a literal transcription of the loop, with tool sources inlined verbatim. You can read it, diff it, and run it after you stop using bare-agent entirely. That is the point.

What this means in practice: no metaclass magic, no hidden DAG executor, no god-object to subclass, no state trapped in a session. Extensibility is composition — AgentLoop(llm=..., approver=..., registry=...) — not inheritance.

Features

The 8 primitives

Each is independently usable — not a god-object:

The four seams

Extensibility here is composition: you pass a different object, never set a flag on a closed framework. Each seam is a duck-typed Protocol, so anything with the right methods works — no base class to inherit.

Tools that live somewhere else

The decorator derives a tool's schema and its validation from a Python class, which only works for a tool defined in your own process. A tool reached over MCP, OpenAPI, or another agent is described by a schema that arrives at runtime and is validated by whoever owns it:

registry.register(
    name="get_dish_info",
    description="Look up one dish by exact name.",
    parameters=mcp_tool.input_schema,        # the schema as it came off the wire
    func=lambda arguments: session.call_tool("get_dish_info", arguments),
)

Such a tool publishes its schema verbatim and receives the raw argument dict — the registry does not re-validate it. That is deliberate: a local check would duplicate the remote's own validation and, worse, swallow the remote's error response, which is usually the thing the caller actually needs to see.

Providers that shape a turn differently

Chat Completions writes one assistant message carrying a tool_calls array. The OpenAI Responses API writes the same turn as N+1 separate items. A Transcript owns that difference, so the loop never has to know:

class ResponsesTranscript:
    def seed(self, system_prompt: str, user_input: str) -> list[dict]:
        return [{"role": "user", "content": user_input}]   # system travels out of band

    def assistant_message(self, response: LLMResponse) -> list[dict]:
        ...   # one message item + one function_call item per call

    def tool_message(self, call: ToolCallRequest, result: ToolResult) -> dict:
        ...   # {"type": "function_call_output", "call_id": ..., "output": ...}

agent = AgentLoop(..., transcript=ResponsesTranscript())

The loop decides when to append; the transcript decides what is appended — including the <untrusted_tool_output> fence, so a transcript can choose a different containment strategy.

Governing the run

Budget is the one thing that is a value rather than a seam:

Budget(
    max_turns=4,
    max_tokens=1_000_000,
    max_wallclock_s=120.0,
    max_cost_usd=1.0,
    max_identical_calls=0,   # 0 disables the cycle guard; the other axes still terminate
)

max_identical_calls stops a run that keeps making the same call with the same arguments. It defaults to 3. Set it to 0 when you want termination to depend only on turn count — a demo that must stop after a predictable number of rounds, say.

Seeing what the model thought

LLMResponse.reasoning carries a reasoning model's summary when the provider returns one. It is kept out of answer — it exists to be shown to a human, never replayed to the model as though it were part of the conversation. The loop emits it as a reasoning event:

async def sink(event):
    if event.kind == "reasoning":
        print(event.data["text"])

await agent.run("...", on_event=sink)

Quickstart

pip install bare-agent   # or: uv add bare-agent

A complete agent in ~30 lines — the docstring becomes the LLM's tool description:

import asyncio
from pydantic import BaseModel, Field
from bare_agent import AgentLoop, Budget, LLMClient, ToolRegistry, get_settings

registry = ToolRegistry()

class AddArgs(BaseModel):
    a: int = Field(description="first addend")
    b: int = Field(description="second addend")

@registry.tool()
async def add(args: AddArgs) -> int:
    """Add two integers and return their sum."""
    return args.a + args.b

async def main() -> None:
    settings = get_settings()          # local Ollama by default; set BARE_AGENT_MODEL for frontier
    agent = AgentLoop(
        registry=registry,
        llm=LLMClient.from_settings(settings),
        budget=Budget.from_settings(settings),
        system_prompt="You are a precise assistant. Use tools for arithmetic.",
    )
    result = await agent.run("What is 17 + 25, then add 100 to that?")
    print(result.answer)               # -> "142"
    print(result.stop_reason, result.turns, f"${result.cost_usd}")  # -> completed 3 $0.0

asyncio.run(main())

Run it locally for free:

ollama pull qwen3        # one-time
make demo                # or: uv run python examples/quickstart.py

The studio

make web      # FastAPI on :8000 + Next.js studio on :3000 → http://localhost:3000/studio

Open http://localhost:3000/studio: Add agents and wire them into a chain, attach catalog tools, pick a model (local qwen3 at $0 or your frontier key), and Run — each agent streams its turns, tool calls, and tokens live over SSE in its own section. The backend is standalone: make api runs the control plane alone, and the library works with no UI at all.

How it works

user input
   │
   ▼
┌──────────────┐   answer feeds   ┌──────────────┐
│   Agent 1    │ ───────────────► │   Agent 2    │ ──────────►  final answer
│  + tools     │   the next       │  + tools     │
└──────────────┘                  └──────────────┘
   each agent = ONE hand-written loop:
   explicit messages list · 4-axis budget + cycle guard · permission-gated tool dispatch

   run it:   inline over SSE      ·  or  queue → worker pool → KEDA scales 0→N→0
   keep it:  Eject ──► agent.py   (litellm + pydantic only — ZERO bare_agent dependency)

Eject

Any flow — single agent or a chain — compiles to a standalone script that imports only litellm and pydantic. Tool sources are inlined verbatim; there is no bare_agent import:

uv run --with litellm --with pydantic agent.py "your question"

In the studio, Eject to Python shows the generated code and downloads it. The generated file is machine-checked to compile. You can read it, diff it, vendor it, and run it after you stop using bare-agent entirely.

Configuration

Settings are read by Pydantic Settings from the environment (BARE_AGENT_ prefix) or .env.

For a hosted model, set BARE_AGENT_MODEL=anthropic/… and export that provider's key (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY).

Development

make ci          # lock-check + format-check + lint (ruff) + compile + typecheck (ty) + tests (pytest)
make test        # the 29-test suite — hermetic (LLM and Redis are faked; no daemon needed)
make web         # backend + studio together for local hacking
make up / down   # the Docker stack (api + studio; Ollama stays on the host)
make queue-up    # the Docker stack WITH the KEDA-shaped worker plane (+ redis + worker)
make help        # all targets

Kubernetes manifests live in k8s/ — an inline deploy (api + studio) and the KEDA worker plane (redis + worker). The studio has its own toolchain (apps/studio/AGENTS.md); the canonical agent rules for the whole repo are in AGENTS.md.

License

MIT © 2026 Subrata Mondal — see LICENSE. Built as the clean, reusable extraction of Argus's agent runtime.