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.0andfastmcp >= 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)
- Getting Started — toolless chat, structured outputs by return type, per-call overrides, multi-agent patterns.
- Streaming and events —
FluentRun.events(*selectors)and the seven typed selectors. - Depends and tools — value-style injection and sub-agent injection via
Depends(...). - Typed MCP and guardrails — class-based
MCPServerandAnnotated[T, guardrail(...)]metadata. - Escape hatch —
wrapper._agentIS the v1.0Agent; lifespan + drop-down recipes. - Known limitations — what glow does not do yet.
Agent — the canonical, fully-typed surface
- Getting Started — install and run your first agent.
- Agent — the declarative
Agentclass and its collaborator Protocols. - Run —
agent.invoke(msg)returnsRun[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
- API Reference · Migration v0.12 → v1.0 · Error Handling · Observability · Production · Concurrency · Multi-Server · Structured outputs (reference)
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.glowships behind the[glow]extra. What it does not do yet is listed indocs/glow/limitations.md.- JSON output modes do not stream.
JsonOutputandStructuredOutputare single-shot by design; constructingStreamingOutput(base=JsonOutput(...))raisesConfigurationError. - Async-only. The agent loop,
Run, streaming, serving, and testing surfaces are allasync-first; there is no sync facade. Bridge withasyncio.run(...)at your entry point if you need one. - Multi-agent narrative is moving toward
asyncio. The declarativeAgentConfig.sub_agentspath plus the runnable patterns underexamples/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.ymlexpectsGROQ_API_KEYin.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.