Quickstart

In this quickstart guide we’re going to see how to build an AI agent with Timbal. We’ll start from scratch and gradually enhance it with advanced features. Let’s dive in! Before moving forward, complete the installation steps. You need Python 3.11 or newer, the Timbal CLI, uv, and Bun. timbal start runs uv for each workforce member and bun for the API and UI, and it stops if either tool is missing.

Run without an API key

TestModel answers from a list you provide. It does not call a provider and does not need a key. Import it from timbal.core.

import asyncio

from timbal import Agent
from timbal.core import TestModel


async def main() -> None:
    agent = Agent(
        name="my_agent",
        model=TestModel(responses=["Hello from Timbal."]),
    )
    result = await agent(prompt="Say hello").collect()
    print(result.status.code)
    print(result.output.collect_text())


asyncio.run(main())

[info] Using in-memory tracing provider. event_name=tracing_setup run_id=<run id>
success
Hello from Timbal.

The tracing line is logged before the prints. The run id changes every execution. Debug lines about platform config only show when debug logging is on. collect() is a method of the object agent(...) returns, not of Agent. Pass responses or a handler(messages); do not pass both. model.call_count increments once per model call. Swap the same agent to a string model (openai/gpt-5-mini and an OPENAI_API_KEY, or platform auth from timbal configure) when you want a live answer. A voice session cannot use TestModel for speech; see Your first voice agent.

Create a Timbal Project

Run the following Timbal CLI command to create a new project:

timbal create my-project

This will prompt you interactively to choose what you want to build (Agent or Workflow) and what UI you want for your project. After making your selections, it creates a project structure with all the necessary files and dependencies to get started.

Project Structure

After running the command, your project will look like this:

my-project/
├── api/              - Elysia API server (Bun)
├── workforce/        - Your timbal components (Python)
│   └── <name>/
│       ├── agent.py  - Main app logic (or workflow.py for workflows)
│       ├── timbal.yaml    - Timbal configuration
│       └── pyproject.toml - Python dependencies
├── ui/               - React + Vite + TypeScript + shadcn (Bun) [optional]
├── .gitignore        - Git ignore file
└── README.md         - Project documentation

Directory/File	Purpose
api/	Elysia API server running on Bun
workforce/	Your timbal components (Python). Contains subdirectories for each agent or workflow
workforce/<name>/agent.py	Main application file where you define your AI agents. If you create a workflow, you’ll have a `workflow.py` file instead
workforce/<name>/pyproject.toml	Python project configuration and dependency management
workforce/<name>/timbal.yaml	Timbal deployment configuration and settings
ui/	React + Vite + TypeScript + shadcn running on Bun (only if UI is selected)

Run locally

Run timbal configure before your first timbal start — it stores your Timbal credentials locally. For model calls, platform auth from configure is enough; otherwise set OPENAI_API_KEY in <project>/.env (or the key for whichever provider your model uses). From the project directory, start the full stack — API, workforce (your Python agents/workflows), and UI if you included one:

cd my-project
timbal start

timbal start prints the local URLs and keeps services running until you quit (q). While it’s running you can press o to open the UI in your browser, or h for other commands. If <project>/.env exists, timbal start loads it automatically and injects those variables into every service (UI, API, and all workforce members). Per-member overrides can live in workforce/<name>/.env. See Environment variables for scoping, precedence, and overrides.

To test a workforce member in isolation, you can also run its Python file directly: uv run python workforce/<name>/agent.py (the scaffold includes a small terminal REPL).

Customize your agent

timbal create scaffolds a starter agent.py (or workflow.py) under workforce/<name>/. Open that file and edit the Agent definition. A minimal agent needs only a name and model:

agent.py

from timbal import Agent

agent = Agent(
    name="my_agent",
    model="openai/gpt-5-mini"
)

If you use your own provider key instead of platform auth, set it in a .env file at the project root (e.g. OPENAI_API_KEY for OpenAI models) — timbal start picks it up automatically. Never commit .env to version control.

The scaffold already includes a terminal REPL (main() at the bottom of agent.py). After editing, restart with timbal start to pick up changes in the full app, or run the file directly for a quick loop. You can learn more about the Agent class and all the available options in the Agents section.

Adding Tools

Agents become powerful with tools. In Timbal, you can use both built-in tools and custom tools (functions you write yourself).

Built-in tools

Timbal includes several ready-to-use tools. For example, the WebSearch tool allows your agent to search the internet for real-time information:

agent.py

from timbal import Agent
from timbal.tools import WebSearch

agent = Agent(
    name="my_agent",
    model="openai/gpt-5-mini",
    tools=[WebSearch()]
)

Custom Tools

Creating custom tools is straightforward—just write a function. Here’s a simple example that returns the current date and time:

agent.py

from datetime import datetime

from timbal import Agent
from timbal.tools import WebSearch

def get_datetime() -> str:
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

agent = Agent(
    name="my_agent",
    model="openai/gpt-5-mini",
    tools=[WebSearch(), get_datetime]
)

You can combine any number of tools to create powerful, specialized agents. Mix and match baked-in and custom tools to fit your specific use case. You can even use agents and workflows as tools!

Congratulations! You’ve built a fully functional AI agent with tools in just a few lines of code.Ready to explore more? Check out our examples, or browse the latest code samples on GitHub.

Moving to Production

Ready to take your agent to production? Timbal provides enterprise-grade deployment options designed for real-world applications. Whether you need fully managed hosting or complete infrastructure control, we’ve got you covered. Check out our comprehensive deployment guide to explore your options and choose the best approach for your needs.

Getting started

Core Concepts

Agents

Voice Agents

Workflows

Human in the Loop

Evals

Deployment

Run without an API key

Create a Timbal Project

Project Structure

Run locally

Customize your agent

Adding Tools

Built-in tools

Custom Tools

Moving to Production

​Run without an API key

​Create a Timbal Project

​Project Structure

​Run locally

​Customize your agent

​Adding Tools

​Built-in tools

​Custom Tools

​Moving to Production

Run without an API key

Create a Timbal Project

Project Structure

Run locally

Customize your agent

Adding Tools

Built-in tools

Custom Tools

Moving to Production