Skip to main content

​
What is Timbal?

Timbal is an open-source Python framework for building reliable AI applications. It gives you two primitives, Agents for autonomous reasoning and Workflows for explicit pipelines, plus everything you need to take them to production: a stable multi-provider model layer, memory, tracing, and evals. There’s no hidden magic. Under the hood it’s async functions, Pydantic validation, and event-driven streaming. If you know async/await, you already know how Timbal works.

​
Agents vs Workflows

Agents are autonomous execution units that orchestrate LLM calls and tool use. The model decides what to do. Best for:
  • Open-ended problem solving and multi-step reasoning
  • Dynamic tool selection based on context
  • Multi-turn conversations with memory
Workflows are explicit, step-by-step pipelines. You define the steps, and the framework infers dependencies and runs independent steps concurrently. See the workflows guide for control flow, branching, and composition. Best for:
  • Multi-stage data processing
  • Predictable, deterministic execution paths
  • Performance-critical work that benefits from parallelism
Both share the same interface and emit the same event stream, so you can compose them freely. An Agent can be a Workflow step, and a Workflow can be an Agent’s tool.

​
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 to isolate framework cost), Timbal runs agent loops several times faster while using a fraction of the memory.
  • Simple and hackable. The core framework is under 10k lines with no hidden magic, just async functions and Pydantic. You can read it, modify it, and fork it to fit your needs. The others are bloated with legacy, indirection, and abstraction that make doing the same nearly impossible.
  • One interface. Agents, Workflows, and Tools share the same calling convention and event stream. Learn it once.
  • Provider-agnostic. Swap models by changing a string. Built-in FallbackModel chains providers for automatic failover.
  • Production-shaped. Refined in production before open-sourcing. Fast failure, clear errors, stable interfaces.
  • Stable in a chaotic ecosystem. Providers ship breaking changes monthly. Timbal absorbs the churn so your code doesn’t have to.

​
Key Features

Memory

Persistent context with built-in compaction for long conversations.

Model Routing

One interface across every provider, with fallback chains for failover.

Tools & MCP

A built-in tool library, your own functions, and any MCP server.

Structured Output

Get typed Pydantic models back instead of raw text.

Human in the Loop

Pause for approval or input, then resume across process restarts.

Skills

Reusable tool packages the agent loads on demand.

Tracing

Every run produces a full span trace, exportable over OTLP.

Evals

Declarative YAML evaluation suite with built-in validators.

Deployment

Run the full stack locally with timbal start, then ship it.
New here? Head to the Quickstart to build and run your first agent.