---
title: "Quickstart"
description: "Build your first AI application with Timbal in just 5 lines of code"
---

We'll start implementing an Agent. It will be a simple chatbot and gradually enhance it with advanced features. Let's dive in!

Before moving forward, ensure you've completed the installation of Timbal. If you haven't set it up yet, follow the [installation guide](/installation) to get started.

## Part 0: Initialize a Timbal Project

<Steps>
  <Step title="Create Project Structure">
    Run the Timbal CLI command to create a new project:
    ```bash
    timbal init my-project
    ```
    This creates a complete project structure with all necessary files and dependencies.
  </Step>
  <Step title="Project Structure">
    Your project will look like this:
    <img
      src="/images/project-structure.png"
      alt="Project structure"
      style={{width: '300px'}}
      noZoom
      className="rounded-lg"
    />
    | File | Purpose |
    |------|---------|
    | **.venv** | Python virtual environment directory (automatically created) |
    | **.dockerignore** | Docker configuration for containerized deployment |
    | **agent.py** | Main application file where you define your AI agents and workflows |
    | **pyproject.toml** | Python project configuration and dependency management |
    | **timbal.yaml** | Timbal framework configuration and settings |
    | **uv.lock** | Dependency lock file for reproducible builds |
  </Step>
  <Step title="Edit Your Agent">
    Out of all those files, you only need to edit one to customize your agent: `agent.py`. Here's an example:
    ```python 
    from datetime import datetime

    from timbal import Agent
    from timbal.handlers.docx import create_docx

    def get_datetime() -> str:
        return datetime.now().isoformat()

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

    await agent(prompt="What time is it?").collect()
    await agent(prompt="Cool, write that down on a word file for me").collect()
    ```
    <Info>
    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.
    </Info>
  </Step>
  <Step title="Run Your Agent">
    Run your agent using Python:
    ```bash
    python agent.py
    ```
    Or with uv:
    ```bash
    uv run agent.py
    ```
    Your agent will start and be ready to receive prompts!
  </Step>
</Steps>

As you build more complex agents, you'll need additional Python packages for features like database connections, API integrations, or specialized tools.

<Info>
Timbal automatically sets up a Python environment using `uv`. You can manage your project dependencies using `uv` commands just like in any other Python project. For example:

```bash
uv add package-name
```

This makes it easy to add new packages and manage your project's dependencies.
</Info>

## Part 1: Build a Simple Chatbot

🛠 Let's create a simple chatbot that can respond to user messages.

**1. Import the class `Agent` from the `timbal` package.**

```python
from timbal import Agent
```

**2. Initialize an `Agent` object.**

```python
agent = Agent(
    name="my_agent",
    model="gemini/gemini-2.5-pro-preview-03-25" # provider/model
)
```

The `name` parameter is required and provides a unique identifier for your agent. The `model` parameter specifies the provider and model to use for the agent.

**3. Set your environment variables**
Before running your flow, make sure you have the keys needed set as environment variables in your `.env` file:

👀 It will depend on the LLM you're using, in this case we are using a Gemini model

```bash
GEMINI_API_KEY=your_api_key_here
```

Only with the `Agent` class we have a flow that represents a llm that receives a `prompt` and returns a `response`.

Now let's run the chatbot!

```python
response = await agent(prompt="What is the capital of Germany?").collect()
print(response.output.content[0].text)
```


You will see an output like this:

```bash
The capital of Germany is Berlin.
```


<Tip>
You've just created your first Timbal flow!
</Tip>

This is the **simplest flow** you can create.

You can modify it as you want. For example, you can add tools to the agent.

## Part 2: Enhancing the Chatbot with Tools

A great feature of Timbal is that you can easily add tools to your agent, allowing it to perform actions or fetch information in real time. 

You can use both **prebuilt tools** (already provided by Timbal or the community) and **custom tools** (functions you create yourself).

Let's see both approaches with practical examples:

### Example 1: Using a Prebuilt Tool

Timbal comes with several tools ready to use. Here are two powerful examples:

#### a) Internet Search

You can use the search tool to let your agent search the internet for up-to-date information:

```python
from timbal.steps.perplexity import search

agent = Agent(
    name="search_agent",
    model="gemini/gemini-2.5-pro-preview-03-25",
    tools=[search]
)
```

#### b) SQL/Postgres Query

Timbal also provides a prebuilt tool to query a Postgres database:

```python
from timbal.steps.sql.postgres import postgres_query, PGConfig

db_config = PGConfig(
    host="localhost",
    port=5432,
    user="youruser",
    password="yourpassword",
    database="yourdb"
)

def run_sql_query(sql: str) -> str:
    result = postgres_query(sql, db_config=db_config)
    return str(result)

agent = Agent(
    name="sql_agent",
    model="gemini/gemini-2.5-pro-preview-03-25",
    tools=[run_sql_query]
)
```


### Example 2: Creating Your Own Tool

You can also create your own tools. Here's a very simple example: a tool that returns the current date and time.

```python
from datetime import datetime

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

agent = Agent(
    name="datetime_agent",
    model="gemini/gemini-2.5-pro-preview-03-25",
    tools=[get_datetime]
)
```

With Timbal, you can combine as many tools as you want—prebuilt or custom—to make your agent as powerful as you need!

**That's it!** With 5 lines of code we've created a chatbot with tools.

_Looking for the full list of integrations or examples?_

_Head over to [integrations](/integrations)/[examples](/examples) or, even better, check out our_ <a href="https://github.com/timbal-ai/timbal" target="_blank" rel="noopener noreferrer">GitHub</a>! _We're adding new examples as fast as we can._ 

_Want the latest and greatest? Just do a <b>git pull</b> to make sure you have all the newest content! 😄_

## 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](/deployment) to explore your options and choose the best approach for your needs.
