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, ensure you’ve completed the installation steps.
Create a Timbal Project
Run the following Timbal CLI command to create a new 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) |
You have your project structure set up. Next, you only need to edit the agent.py file (or workflow.py for workflows) in the workforce/<name>/ directory to customize your agent’s behavior and capabilities.
Build a simple Agent
Let’s create a simple agent with the Agent class:
from timbal import Agent
agent = Agent(
name="my_agent",
model="openai/gpt-5-mini"
)
You’ll need to set the appropriate environment variables for your chosen model (e.g., OPENAI_API_KEY). Store these in a .env file and never commit them to version control.
async def main():
while True:
prompt = input("User: ")
if prompt == "q":
break
agent_output_event = await agent(prompt=prompt).collect()
print(f"Agent: {agent_output_event.output}") # noqa: T201
if __name__ == "__main__":
import asyncio
asyncio.run(main())
You’ve just created your first Timbal agent. Next, you can add any type of tools to it to make it more powerful.
WebSearch tool allows your agent to search the internet for real-time information:
from timbal import Agent
from timbal.tools import WebSearch
agent = Agent(
name="my_agent",
model="openai/gpt-5-mini",
tools=[WebSearch()]
)
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]
)
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. 
