Getting Started¶

This guide will help you install Tinygent and create your first agent.

Prerequisites¶

Before you begin, ensure you have:

Python 3.10+ installed
Git for cloning the repository
uv - Modern Python package manager

Installing uv¶

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Via pip
pip install uv

Installation¶

From Source¶

Clone the repository

git clone git@github.com:filchy/tinygent.git
cd tinygent

Create a virtual environment

uv venv --seed .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install Tinygent

Option A: Core only (minimal installation)

uv sync

Option B: With specific providers

# OpenAI
uv sync --extra openai

# Anthropic
uv sync --extra anthropic

# Multiple providers
uv sync --extra openai --extra anthropic --extra mistralai

Option C: Everything (including dev tools and all packages)

uv sync --all-groups --all-extras

Install in editable mode (for development)

uv pip install -e .

Configuration¶

API Keys¶

Tinygent uses environment variables for API keys. Set them before running your code:

# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Mistral AI
export MISTRAL_API_KEY="..."

# Google Gemini
export GEMINI_API_KEY="..."

# VoyageAI (embeddings)
export VOYAGEAI_API_KEY="..."

# Brave Search
export BRAVE_API_KEY="..."

Pro Tip: Create a .env file in your project root:

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Then load it in your code:

from dotenv import load_dotenv
load_dotenv()

Your First Agent¶

Let's build a simple weather assistant.

Step 1: Create a Tool¶

Tools are functions that agents can call. Use the @tool decorator:

from tinygent.tools import tool

@tool
def get_weather(location: str) -> str:
    """Get the current weather in a given location.

    Args:
        location: The city or location to get weather for

    Returns:
        A string describing the current weather
    """
    # In a real app, you'd call a weather API
    return f'The weather in {location} is sunny with a high of 75°F.'

Step 2: Build an Agent¶

Use the factory function to create a ReAct agent:

from tinygent.core.factory import build_agent

agent = build_agent(
    'react',                    # Agent type
    llm='openai:gpt-4o-mini',  # LLM provider:model
    tools=[get_weather],        # List of tools
    max_iterations=5,           # Max reasoning loops
)

Step 3: Run the Agent¶

# Synchronous
result = agent.run('What is the weather like in Prague?')
print(result)

# Asynchronous with streaming
import asyncio

async def main():
    async for chunk in agent.run_stream('What is the weather in Prague?'):
        print(chunk, end='', flush=True)

asyncio.run(main())

Complete Example¶

# weather_agent.py
from tinygent.tools import tool
from tinygent.core.factory import build_agent

@tool
def get_weather(location: str) -> str:
    """Get the current weather in a given location."""
    return f'The weather in {location} is sunny with a high of 75°F.'

@tool
def get_forecast(location: str, days: int = 3) -> str:
    """Get the weather forecast for the next few days."""
    return f'{days}-day forecast for {location}: Sunny, then partly cloudy.'

def main():
    agent = build_agent(
        'react',
        llm='openai:gpt-4o-mini',
        tools=[get_weather, get_forecast],
    )

    result = agent.run(
        'What is the weather in Prague? Also give me a 5-day forecast.'
    )
    print(result)

if __name__ == '__main__':
    main()

Run it:

export OPENAI_API_KEY="your-key"
uv run weather_agent.py

Understanding the Output¶

When you run the agent, you'll see the ReAct reasoning cycle:

Thought: Agent reasons about what to do
Action: Agent decides to call a tool
Observation: Tool returns a result
Repeat: Until agent has enough information
Final Answer: Agent provides the answer to the user

Next Steps¶

Now that you have a working agent, explore more concepts:

Agents: Learn about different agent types (ReAct, MultiStep, Squad, MAP)
Tools: Discover @reasoning_tool and @jit_tool
Memory: Add conversation memory to your agents
LLMs: Use different LLM providers
Middleware: Customize agent behavior with hooks

Running Examples¶

Tinygent includes many examples in the examples/ directory:

# ReAct agent
uv run examples/agents/react/main.py

# Multi-step agent
uv run examples/agents/multi-step/main.py

# Memory examples
uv run examples/memory/basic-chat-memory/main.py

# Tool usage
uv run examples/tool-usage/main.py

Explore the examples to see advanced patterns and use cases.

Troubleshooting¶

Import Errors¶

If you get import errors, ensure you've installed the package:

uv pip install -e .

Missing Dependencies¶

Install the provider you need:

uv sync --extra openai

API Key Issues¶

Verify your environment variables are set:

echo $OPENAI_API_KEY

Development Setup¶

For contributors and advanced users:

# Install with all dev dependencies
uv sync --all-groups --all-extras

# Format code
uv run fmt

# Run linter and type checker
uv run lint

# Run tests (if available)
pytest

What's Next?¶

Learn Core Concepts

Understand agents, tools, and memory

Core Concepts
Build Custom Tools

Create powerful custom tools for your agents

Tool Guide
Advanced Agents

Build multi-agent systems and complex workflows

Agent Guide