Build AI agents that actually work. Turn any Python function into an autonomous tool with a single decorator.
from tinyagent import tool, ReactAgent @tool def multiply(a: float, b: float) -> float: """Multiply two numbers.""" return a * b @tool def divide(a: float, b: float) -> float: """Divide two numbers.""" return a / b agent = ReactAgent(tools=[multiply, divide]) result = agent.run("What is 12 times 5, then divided by 3?") # → 20That's it. The agent reasons through the steps:
- Calls
multiply(12, 5)→ 60 - Calls
divide(60, 3)→ 20 - Returns the answer
| Feature | Benefit |
|---|---|
| Zero boilerplate | Just decorate functions with @tool |
| Auto-reasoning | Agent figures out which tools to call and when |
| LLM-agnostic | Works with OpenRouter, OpenAI, Claude, Llama, etc. |
| Type-safe | Full type hints and validation built-in |
| Production-ready | Error handling, retries, and observability |
# Recommended: UV (10x faster venv creation) uv venv && source .venv/bin/activate uv pip install tiny_agent_os # Or with pip pip install tiny_agent_os1. Get an API key from openrouter.ai
2. Set environment variables:
export OPENAI_API_KEY=your_key_here export OPENAI_BASE_URL=https://openrouter.ai/api/v13. Create your first agent:
from tinyagent import tool, ReactAgent @tool def add(a: float, b: float) -> float: """Add two numbers.""" return a + b agent = ReactAgent(tools=[add]) print(agent.run("What is 5 plus 3?"))Note: This is a clean rewrite focused on keeping tinyAgent truly tiny. For the legacy codebase (v0.72.x), install with
pip install tiny-agent-os==0.72.18or see the0.72branch.
As of v0.73, tinyAgent's internal structure has been reorganized for better maintainability:
tinyagent/agent.py→tinyagent/agents/agent.py(ReactAgent)tinyagent/code_agent.py→tinyagent/agents/code_agent.py(TinyCodeAgent)
The public API remains unchanged - you can still import directly from tinyagent:
from tinyagent import ReactAgent, TinyCodeAgent, tooltinyAgent supports any LLM via OpenRouter:
from tinyagent import ReactAgent # Cheap & fast agent = ReactAgent(tools=[...], model="gpt-4o-mini") # Most capable agent = ReactAgent(tools=[...], model="anthropic/claude-3.5-sonnet") # Open source agent = ReactAgent(tools=[...], model="meta-llama/llama-3.1-70b-instruct")Default: Uses gpt-4o-mini if no model is specified.
from tinyagent import tool, ReactAgent @tool def percent(value: float, pct: float) -> float: """Calculate percentage of a value.""" return value * (pct / 100) @tool def subtract(a: float, b: float) -> float: """Subtract b from a.""" return a - b agent = ReactAgent(tools=[percent, subtract]) result = agent.run("If I have 15 apples and give away 40%, how many are left?") # Agent: calculates 40% of 15 (6) → subtracts (15 - 6 = 9) → answers "9 apples left"from tinyagent import ReactAgent from tinyagent.tools.builtin import web_search agent = ReactAgent(tools=[web_search]) result = agent.run("Compare FastAPI vs Django performance") # Set your key first: export BRAVE_SEARCH_API_KEY=your_keyfrom tinyagent import TinyCodeAgent agent = TinyCodeAgent(tools=[]) result = agent.run("Generate 10 random numbers and show the average") # Agent writes and executes Python code to solve this- Reasons through multi-step problems
- Automatically chains tool calls
- Includes retry logic and error handling
agent = ReactAgent(tools=[multiply, divide]) agent.run("What is 100 divided by 5, times 3?")- Writes and executes Python code
- Sandboxed with restricted imports
- Perfect for data processing and calculations
agent = TinyCodeAgent() agent.run("Generate 100 random numbers and show the median")Create tools by decorating functions:
@tool def fetch_data(id: int) -> dict: """Fetch user data by ID.""" return {"id": id, "name": "Alice"} @tool def format_csv(data: list) -> str: """Convert list to CSV format.""" return ",".join(str(d) for d in data)Tool best practices:
- Atomic — Do one thing well
- Typed — Use type hints
- Documented — Write clear docstrings (LLM reads these!)
Load your own system prompts from files:
agent = ReactAgent( tools=[...], prompt_file="path/to/custom_prompt.txt" )Supports .txt, .md, .prompt extensions. Falls back to defaults if missing.
- Tool Creation Guide — Detailed patterns and best practices
- Architecture Diagrams — System design and execution flow
- API Reference — Quick reference for all APIs
BETA — Actively developed and production-ready. Breaking changes possible until v1.0.
Questions? Open an issue
Business Source License 1.1
Free for:
- Individuals
- Small businesses (< $1M annual revenue)
Larger organizations: Please contact info@alchemiststudios.ai
Made by @tunahorse21 at alchemiststudios.ai