Skip to main content

t0-agents

t0-agents

The Pythonic agentic framework for TensorZero. Build LLM agents that discover and execute tools through MCP (Model Context Protocol), while TensorZero handles inference routing, episode tracking, and ClickHouse-backed observability for you. Two surfaces, one engine: t0_agents.glow for the four-line decorator path, the canonical Agent surface for the moments you need every escape hatch.

Status: Beta, built and used in production by Vest. Requires tensorzero >= 2026.6.0 and fastmcp >= 3.2.3.

Four lines, one agent.

from t0_agents.glow import App
app = App(t0=t0)

@app.agent("tutor")
async def tutor(query: str) -> str:
    """An English tutor that explains grammar like you're 12."""

print(await tutor("How do I say hello in formal Japanese?"))

The docstring is the system prompt. The return annotation picks the OutputMode. await tutor(...) returns the unwrapped string directly. Install with the [glow] extra (Install). Full tour at docs/glow/.

When you need the controls — drop down to Agent.

from t0_agents import Agent, AgentConfig

# Construct once, run many.
agent = Agent(AgentConfig(
    name="assistant",
    function_name="agent",
    middleware=[TimingMiddleware(), MyGuardrails()],   # Starlette-style chain
), t0=t0, tool_provider=client)

# invoke(...) returns a Run[T] — the first-class invocation handle.
run = agent.invoke("Plan my trip to Lisbon under $1500.")

# Iterate live AgentEvent stream:
async for event in run.events():
    ...

# Cooperative cancellation:
await run.cancel()

# Await the terminal AgentResult:
result = await run                      # episode_id, inference_ids, cost
forked = await run.fork("Make it Madrid instead.")

# Polymorphic outputs — typed end-to-end.
from t0_agents import StructuredOutput
from pydantic import BaseModel

class Customer(BaseModel):
    name: str
    email: str

extractor = Agent(AgentConfig(
    name="extractor",
    function_name="extract_customer",
    output=StructuredOutput(Customer),
), t0=t0)
parsed = (await extractor.invoke("Sarah <sarah@example.com>")).value
parsed.email                            # statically typed Customer

And toolless chat works the same way — drop tool_provider, get a pure-conversation Agent with zero MCP plumbing:

chat = Agent(AgentConfig(name="tutor", function_name="agent"), t0=t0)
result = await chat.invoke("Explain monads in two sentences.")
print(result.response)

No Client, no FastMCP server, no list_tools() roundtrip per turn — the loop runs one inference and returns the text response.

Glow compiles down to exactly this Agent. Every glow wrapper exposes _agent — the same v1.0 surface — for the moments the decorator is in your way. See docs/glow/escape-hatch.md.

Each axis pairs with one chapter of the docs: Run · Middleware · Output Modes. Multi-agent topologies are built directly from these primitives plus plain asyncio — see the runnable patterns under examples/agent/12_concurrency/ and examples/glow/, documented in Multi-Agent.

Why t0-agents

Most agentic frameworks try to be everything at once. They reimplement inference routing, prompt versioning, tool discovery, observability and human-in-the-loop — and as a result they reimplement most of those things badly.

t0-agents takes the opposite bet. Two upstream projects already solved the hard parts:

  • TensorZero owns inference: gateway routing, provider fallback, prompt versions, episode IDs, ClickHouse analytics, A/B testing.
  • FastMCP (Model Context Protocol) owns tools: dynamic discovery, schema evolution, sticky-session HTTP transport, the elicitation primitive for human-in-the-loop.

t0-agents is the thin glue between them. The mcp/ submodule fits in ~100 lines of production code; everything above it — Agent, Run[T], Middleware, OutputMode[T], memory, guardrails, streaming, multi-agent, HTTP serving, the test harness, and the glow decorator skin — is opt-in.

Install

You pay only for what you use. Base = adapter + loop + Agent + InMemoryMemory + guardrails + streaming + composition + testing. Everything that pulls a heavier third-party dependency lives behind an optional extra. Install from PyPI:

# Base install (no Docker, no FastAPI, no SQLite).
pip install t0-agents

# With the extras you need:
pip install "t0-agents[glow,memory-sqlite,serve,pydantic]"
Extra Adds
glow pydantic + the @app.agent decorator surface (the four-line path)
memory-sqlite aiosqlite for cross-process memory and usage persistence
serve FastAPI + Uvicorn + Pydantic + sse-starlette for HTTP serving
pydantic Pydantic for StructuredOutput[M]

Or with uv:

uv add "t0-agents[glow]"

Or straight from a release tag:

pip install "t0-agents[glow] @ git+https://github.com/vest-investments/t0-agents.git@v2.14.1"

Documentation

The public docs are written as a progressive tour: each chapter picks up the tension the previous one left open. Start at the index for the full Reading path and Appendices.

glow — the four-line path (start here)

Agent — the canonical, fully-typed surface

  • Getting Started — install and run your first agent.
  • Agent — the declarative Agent class and its collaborator Protocols.
  • Run — agent.invoke(msg) returns Run[T]: await, iterate events, cancel, replay, fork.
  • Middleware — composable cross-cutting concerns (memory, guardrails, cost, retry…).
  • Output Modes — chat strings, JSON dicts, Pydantic models, tool-call routers, streaming.
  • Concepts — pop the hood: what agent.invoke() actually does, turn by turn.
  • Elicitation — tools that pause to ask humans questions.
  • Memory — remember across turns and across processes.
  • Guardrails — constrain what the agent may do.
  • Streaming — narrate the loop live with typed events, SSE, and WebSocket.
  • Multi-Agent Composition — declarative sub_agents=[...], the LLM-driven path.
  • Serving — create_app(agent) and the FastAPI surface.
  • Testing — keep every layer above from regressing, including in-memory MCP mounts.

Appendices

Guides — production patterns that compose t0-agents with adjacent tooling:

Runnable examples for every chapter live under examples/ — examples/glow/ is the 8-example progressive tour on top of the decorator surface; examples/agent/ has 15 area-by-area examples on top of the canonical Agent surface.

Features

Every layer is opt-in. The base install gets you the core stack; heavier extras live behind named installs.

Capability What it gives you
MCP adapter & loop Convert FastMCP tool definitions to TensorZero's inference format, orchestrate the turn-based inference-execute loop, serialize tool results back. Low-level run_agent for full control.
Run[T] handles agent.invoke(msg) returns a Run you can await, iterate with .events(), cancel, replay, fork, and attach feedback to.
Middleware chain Memory, guardrails, cost tracking, usage ledger, sub-agent orchestration, JSON retry — all composable middlewares; add your own without forking core/agent.py.
OutputMode[T] polymorphism ChatOutput, JsonOutput, StructuredOutput[M] (Pydantic), ToolCallOutput, StreamingOutput. Custom modes (YAML, Instructor, SQLAlchemy) plug in via the same protocol.
glow decorator surface FastAPI-style @app.agent over the v1.0 primitives. Docstring = system prompt, return annotation = OutputMode, Depends(...) for tools and sub-agents, Annotated[T, guardrail(...)] for policy as type metadata.
Cross-run memory InMemoryMemory, SqliteMemory, TensorZeroMemory, or your own MemoryProvider. Keyed by TensorZero's episode_id.
Elicitation forwarding ElicitationForwarder bridges MCP ctx.elicit() requests to your transport (FastAPI/SSE, WebSocket, queue). Pause a tool to ask a human, resume the loop with the response. See docs/elicitation.md and docs/guides/elicitation-in-api.md.
Policy guardrails require_approval, max_cost, max_tool_calls, block_tools out of the box; custom Guardrail Protocol for domain rules. Every decision is captured on AgentResult.guardrail_log for audit.
Multi-agent composition Register sub-agents on AgentConfig.sub_agents and they become {name}_ask tools on the orchestrator's MCP server. Nested orchestrators, parent_episode_id correlation.
HTTP serving create_app(agent) wraps any agent in a FastAPI app with /chat, /feedback, /health, /info — plus /chat/stream (SSE) and /chat/ws (WebSocket) when streaming=True.
First-class testing MockGateway + MockToolProvider for deterministic unit tests, glow_tools + ScriptedElicitation to drive in-memory MCP mounts and ctx.elicit round-trips through the real FastMCP boundary, EmbeddedGatewayHelper for real-inference integration tests without Docker, ten assert_* helpers.
Observability Every run returns the TensorZero episode_id, per-turn inference_ids, the guardrail log, aggregated cost / usage, and a response_source signal.

Status & Limitations

t0-agents is Beta: the API may still change between minor versions, and every change is recorded in CHANGELOG.md. Pin a version (t0-agents==X.Y.Z) or a release tag when consuming from another project; see Install.

Known caveats today:

  • t0_agents.glow ships behind the [glow] extra. What it does not do yet is listed in docs/glow/limitations.md.
  • JSON output modes do not stream. JsonOutput and StructuredOutput are single-shot by design; constructing StreamingOutput(base=JsonOutput(...)) raises ConfigurationError.
  • Async-only. The agent loop, Run, streaming, serving, and testing surfaces are all async-first; there is no sync facade. Bridge with asyncio.run(...) at your entry point if you need one.
  • Multi-agent narrative is moving toward asyncio. The declarative AgentConfig.sub_agents path plus the runnable patterns under examples/agent/12_concurrency/ are the recommended way to wire orchestrators today.

Requirements

  • Python 3.11, 3.12, or 3.13
  • Docker + Docker Compose (for the TensorZero gateway, required by every example beyond the low-level adapter layer)
  • An LLM provider API key (Groq, OpenAI, Anthropic, …) — the default docker-compose.yml expects GROQ_API_KEY in .env

Development

uv sync --all-extras                        # install dev dependencies and every extra
bash ci/checks.sh                           # the gate every pull request runs
uv run pytest -m "not integration and not embedded"   # offline unit tests
uv run pytest -m integration                # requires docker compose up
uv run pytest -m embedded                   # requires RUN_EMBEDDED_TESTS=1 + provider key
uv run ruff check src/ tests/               # lint
uv run mypy src/                            # type check (strict mode)

See CONTRIBUTING.md for the full pull-request workflow and the test-mode cheat-sheet.

License

MIT. See LICENSE.

Metadata

Release files for t0-agents 2.15.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for t0-agents 2.15.0
File Size Uploaded Provenance Actions
t0_agents-2.15.0.tar.gz 1.4 MB Without provenance Details for t0_agents-2.15.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for t0-agents 2.15.0
File Interpreter ABI Platform Actions
t0_agents-2.15.0-py3-none-any.whl Python 3 none any Details for t0_agents-2.15.0-py3-none-any.whl

Total release size: 1.8 MB

Release files / t0_agents-2.15.0.tar.gz

Download URL t0_agents-2.15.0.tar.gz
Size 1.4 MB
Tags Source
SHA-256 checksum
How to use checksums
7bf3aad6ee27d3cf2cb8ef83965dd042c3b278c9c4b2d15d91c52c5cb19dceb7
BLAKE2b-256 checksum
How to use checksums
3b17d3aac571f6715d817c8f3ebb44bd10cc2541455f0d29390f9cf9722a04fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / t0_agents-2.15.0-py3-none-any.whl

Download URL t0_agents-2.15.0-py3-none-any.whl
Size 315.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
03b41872d99335cd769369b081c4e738495944ee7177e09952d8d6c5821b4324
BLAKE2b-256 checksum
How to use checksums
6075d2c601ebd508ec803b1d095777a21683b4beaae073a50719191bfba570b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for t0-agents 2.15.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page