Timbal
Simple, performant, battle-tested framework for building reliable AI applications.
Timbal gives you Agents (autonomous reasoning) and Workflows (explicit pipelines) behind one interface. No hidden magic: async functions, Pydantic validation, and event-driven streaming. If you know async/await, you already know how it works.
Documentation: docs.timbal.ai
Quickstart
pip install timbal
import asyncio
from timbal import Agent
from timbal.tools import WebSearch
agent = Agent(
name="assistant",
model="anthropic/claude-sonnet-4-6",
tools=[WebSearch()],
max_tokens=1024,
)
async def main():
result = await agent(prompt="What's new in AI this week?").collect()
print(result.output)
asyncio.run(main())
Set ANTHROPIC_API_KEY (or the key for your chosen provider) in a .env file or your environment.
Workflows use the same interface:
import asyncio
import httpx
from timbal import Workflow
from timbal.state import get_run_context
async def fetch(url: str) -> str:
async with httpx.AsyncClient(follow_redirects=True) as client:
return (await client.get(url)).text
workflow = (
Workflow(name="scraper")
.step(fetch)
.step(
lambda content: len(content),
content=lambda: get_run_context().step_span("fetch").output,
)
)
async def main():
result = await workflow.collect(url="https://timbal.ai")
print(result.output)
asyncio.run(main())
See the Quickstart for the full app flow (timbal create → timbal start).
Why Timbal
The most performant agent framework. In overhead benchmarks against LangGraph, CrewAI, the OpenAI Agents SDK, PydanticAI, and Agno (observability on both sides, faked LLMs), Timbal runs agent loops several times faster with a fraction of the memory. See Benchmarks.
Small and hackable. The core framework is under 10k lines. Easy to read, modify, and fork. Other frameworks are bloated with legacy, indirection, and abstraction.
One interface. Agents, Workflows, and Tools share the same calling convention and event stream. Compose them freely.
Human in the loop. Approval gates and suspend() pause any run for a human, persist state, and resume across process restarts. Works on agents, workflow steps, and tools.
Provider-agnostic. Swap models by changing a string (anthropic/claude-sonnet-4-6 → openai/gpt-5.5). Built-in FallbackModel chains providers for automatic failover.
Features
| Memory & compaction | Persistent context with strategies to stay under the context window |
| Tools & MCP | Built-in tool library, your own functions, any MCP server |
| Structured output | Typed Pydantic models instead of raw text |
| Skills | Reusable tool packages the agent loads on demand |
| Tracing | Full span traces, exportable over OTLP |
| Evals | Declarative YAML evaluation suite with built-in validators |
| Deployment | Run locally with timbal start, ship to the platform or self-host |
Install extras as needed:
pip install 'timbal[server]' # HTTP serving
pip install 'timbal[documents]' # PDF, Excel, Word
pip install 'timbal[evals]' # evals CLI
pip install 'timbal[all]' # everything
Benchmarks
Pure framework-overhead benchmarks: trivial handlers, faked LLM calls, observability on both sides.
| Metric (single tool call) | Timbal | LangGraph + LangSmith | CrewAI |
|---|---|---|---|
| p50 latency | 1.1 ms | 5.2 ms | 3.2 ms |
| memory / run | 2.2 KB | 110 KB | 10 KB |
| throughput @ c=10 | 1716/s | 224/s | 31/s |
Reproduce with benchmarks/README.md. Full suite covers LangGraph, CrewAI, Agno, PydanticAI, OpenAI Agents SDK, and Google ADK.
Full app
The CLI scaffolds and runs a complete application (UI + API + workforce of Python agents/workflows):
timbal create my-project
cd my-project
timbal start
Deploy by connecting the repo to the Timbal Platform, or self-host the components yourself. See deployment docs.
Development
git clone https://github.com/timbal-ai/timbal.git
cd timbal
uv sync --dev
uv run pytest
Contributor reference: CLAUDE.md, benchmarks/README.md.
Documentation
Contributing
Pull requests and issues welcome.
License
Apache 2.0. See LICENSE.
1 maintainer
Release files for timbal 2.7.24
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| timbal-2.7.24.tar.gz | 25.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| timbal-2.7.24-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 26.5 MB
Release files / timbal-2.7.24.tar.gz
| Download URL | timbal-2.7.24.tar.gz |
|---|---|
| Size | 25.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
23f62f7ea64a1a943cd8490f0be46ab98ab31b33735ee2a3c119ea172ce7a5f9
|
|
BLAKE2b-256 checksum How to use checksums |
7fd838731b4f4633b212b391ee6b7d561115a4911909440d4652adf0e8252405
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / timbal-2.7.24-py3-none-any.whl
| Download URL | timbal-2.7.24-py3-none-any.whl |
|---|---|
| Size | 1.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0f199b8c5057be654b2933f1be52767c9f71e5eec3101779291d9c01228ed023
|
|
BLAKE2b-256 checksum How to use checksums |
8673785e873826d3f8365189c5bc1965653ce7a5c33fc06f00c47e64827b2d93
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
