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

  • Measured framework overhead. The benchmark suite compares agent-loop overhead with fake LLMs to isolate framework cost. Real application latency also depends on models, tools, speech providers, and network calls.
  • Simple and hackable. Python source, async functions, and explicit interfaces make the framework inspectable and extensible.
  • 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 tool-result offloading and compaction for long conversations.

Voice Agents

Streaming speech, interruption handling, browser calls, and telephony with your agent’s tools.

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.