# tinyAgent
Turn any Python function into an AI‑powered agent in just a few lines:
```python
from tinyagent import tool, ReactAgent
@tool
def multiply(a: float, b: float) -> float:
"""Multiply two numbers together."""
return a * b
@tool
def divide(a: float, b: float) -> float:
"""Divide the first number by the second number."""
return a / b
agent = ReactAgent(tools=[multiply, divide])
result = agent.run("What is 12 times 5, then divided by 3?")
# → 20
```
That's it! The agent automatically:
- Understands it needs to perform multiple steps
- Calls `multiply(12, 5)` → gets 60
- Takes that result and calls `divide(60, 3)` → gets 20
- Returns the final answer
## Why tinyAgent?
- **Zero boilerplate** – Just decorate functions with `@tool`
- **Automatic reasoning** – Agent figures out which tools to use and in what order
- **Built-in LLM** – Works out of the box with OpenRouter
- **Type safe** – Full type hints and validation
- **Production ready** – Error handling and retries
## Installation
### Option A: UV (Recommended - 10x Faster)
```bash
uv venv # Creates .venv/
source .venv/bin/activate # Activate environment
uv pip install tiny_agent_os
```
### Option B: Traditional pip
```bash
pip install tiny_agent_os
```
## Quick Setup
Set your API key:
```bash
export OPENAI_API_KEY=your_openrouter_key_here
export OPENAI_BASE_URL=https://openrouter.ai/api/v1
```
Get your key at [openrouter.ai](https://openrouter.ai)
> **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.18` or see the [`0.72` branch](https://github.com/alchemiststudiosDOTai/tinyAgent/tree/0.72).
## Setting the Model
Pass any OpenRouter model when creating the agent:
```python
from tinyagent import ReactAgent, tool
# Default model
agent = ReactAgent(tools=[...])
# Specify a model
agent = ReactAgent(tools=[...], model="gpt-4o-mini")
agent = ReactAgent(tools=[...], model="anthropic/claude-3.5-sonnet")
agent = ReactAgent(tools=[...], model="meta-llama/llama-3.1-70b-instruct")
# TinyCodeAgent works the same way
agent = TinyCodeAgent(tools=[...], model="gpt-4o-mini")
```
## More Examples
### Multi-step reasoning
```python
from tinyagent import tool, ReactAgent
@tool
def calculate_percentage(value: float, percentage: float) -> float:
"""Calculate what percentage of a value is."""
return value * (percentage / 100)
@tool
def subtract(a: float, b: float) -> float:
"""Subtract b from a."""
return a - b
agent = ReactAgent(tools=[calculate_percentage, subtract])
result = agent.run("If I have 15 apples and give away 40%, how many are left?")
print(result) # → "You have 9 apples left."
```
Behind the scenes:
1. Agent calculates 40% of 15 → 6
2. Subtracts 6 from 15 → 9
3. Returns a natural language answer
### Web Search Tool
Built-in web search capabilities with Brave Search API:
```python
from tinyagent import ReactAgent
from tinyagent.base_tools import web_search
# Simple web search with formatted results
agent = ReactAgent(tools=[web_search])
result = agent.run("What are the latest Python web frameworks?")
# Works great for research and comparisons
agent = ReactAgent(tools=[web_search])
result = agent.run("Compare FastAPI vs Django performance")
```
Set your Brave API key:
```bash
export BRAVE_SEARCH_API_KEY=your_brave_api_key
```
## Key Features
### ReactAgent
- **Multi-step reasoning** - Breaks down complex problems automatically
- **Clean API** - Simple, ergonomic interface
- **Error handling** - Built-in retry logic and graceful failures
### Tools Philosophy
Every function can be a tool. Keep them:
- **Atomic** - Do one thing well
- **Typed** - Use type hints for parameters
- **Documented** - Docstrings help the LLM understand usage
## Status
**BETA** - Actively developed and used in production. Breaking changes possible until v1.0.
Found a bug? Have a feature request? [Open an issue](https://github.com/alchemiststudiosDOTai/tinyAgent/issues)!
## License
**Business Source License 1.1**
- Free for individuals and small businesses (< $1M revenue)
- Enterprise license required for larger companies
Contact: [info@alchemiststudios.ai](mailto:info@alchemiststudios.ai)
---
Made by [@tunahorse21](https://x.com/tunahorse21) | [alchemiststudios.ai](https://alchemiststudios.ai) focusing on keeping it "tiny"
Raw data
{
"_id": null,
"home_page": null,
"name": "tiny-agent-os",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, agent, llm, openai, gpt, react",
"author": "alchemiststudios.ai",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c1/2f/25121b1b6466aadaca52ed5010673fe9e6255735ef0c88209a175fd40332/tiny_agent_os-0.73.1.tar.gz",
"platform": null,
"description": "# tinyAgent\n\n\n\nTurn any Python function into an AI\u2011powered agent in just a few lines:\n\n```python\nfrom tinyagent import tool, ReactAgent\n\n@tool\ndef multiply(a: float, b: float) -> float:\n \"\"\"Multiply two numbers together.\"\"\"\n return a * b\n\n@tool\ndef divide(a: float, b: float) -> float:\n \"\"\"Divide the first number by the second number.\"\"\"\n return a / b\n\nagent = ReactAgent(tools=[multiply, divide])\nresult = agent.run(\"What is 12 times 5, then divided by 3?\")\n# \u2192 20\n```\n\nThat's it! The agent automatically:\n- Understands it needs to perform multiple steps\n- Calls `multiply(12, 5)` \u2192 gets 60\n- Takes that result and calls `divide(60, 3)` \u2192 gets 20\n- Returns the final answer\n\n## Why tinyAgent?\n\n- **Zero boilerplate** \u2013 Just decorate functions with `@tool`\n- **Automatic reasoning** \u2013 Agent figures out which tools to use and in what order\n- **Built-in LLM** \u2013 Works out of the box with OpenRouter\n- **Type safe** \u2013 Full type hints and validation\n- **Production ready** \u2013 Error handling and retries\n\n## Installation\n\n### Option A: UV (Recommended - 10x Faster)\n```bash\nuv venv # Creates .venv/\nsource .venv/bin/activate # Activate environment\nuv pip install tiny_agent_os\n```\n\n### Option B: Traditional pip\n```bash\npip install tiny_agent_os\n```\n\n## Quick Setup\n\nSet your API key:\n```bash\nexport OPENAI_API_KEY=your_openrouter_key_here\nexport OPENAI_BASE_URL=https://openrouter.ai/api/v1\n```\n\nGet your key at [openrouter.ai](https://openrouter.ai)\n\n> **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.18` or see the [`0.72` branch](https://github.com/alchemiststudiosDOTai/tinyAgent/tree/0.72).\n\n## Setting the Model\n\nPass any OpenRouter model when creating the agent:\n\n```python\nfrom tinyagent import ReactAgent, tool\n\n# Default model\nagent = ReactAgent(tools=[...])\n\n# Specify a model\nagent = ReactAgent(tools=[...], model=\"gpt-4o-mini\")\nagent = ReactAgent(tools=[...], model=\"anthropic/claude-3.5-sonnet\")\nagent = ReactAgent(tools=[...], model=\"meta-llama/llama-3.1-70b-instruct\")\n\n# TinyCodeAgent works the same way\nagent = TinyCodeAgent(tools=[...], model=\"gpt-4o-mini\")\n```\n\n## More Examples\n\n### Multi-step reasoning\n```python\nfrom tinyagent import tool, ReactAgent\n\n@tool\ndef calculate_percentage(value: float, percentage: float) -> float:\n \"\"\"Calculate what percentage of a value is.\"\"\"\n return value * (percentage / 100)\n\n@tool\ndef subtract(a: float, b: float) -> float:\n \"\"\"Subtract b from a.\"\"\"\n return a - b\n\nagent = ReactAgent(tools=[calculate_percentage, subtract])\nresult = agent.run(\"If I have 15 apples and give away 40%, how many are left?\")\nprint(result) # \u2192 \"You have 9 apples left.\"\n```\n\nBehind the scenes:\n1. Agent calculates 40% of 15 \u2192 6\n2. Subtracts 6 from 15 \u2192 9\n3. Returns a natural language answer\n\n### Web Search Tool\nBuilt-in web search capabilities with Brave Search API:\n\n```python\nfrom tinyagent import ReactAgent\nfrom tinyagent.base_tools import web_search\n\n# Simple web search with formatted results\nagent = ReactAgent(tools=[web_search])\nresult = agent.run(\"What are the latest Python web frameworks?\")\n\n# Works great for research and comparisons\nagent = ReactAgent(tools=[web_search])\nresult = agent.run(\"Compare FastAPI vs Django performance\")\n```\n\nSet your Brave API key:\n```bash\nexport BRAVE_SEARCH_API_KEY=your_brave_api_key\n```\n\n## Key Features\n\n### ReactAgent\n- **Multi-step reasoning** - Breaks down complex problems automatically\n- **Clean API** - Simple, ergonomic interface\n- **Error handling** - Built-in retry logic and graceful failures\n\n### Tools Philosophy\nEvery function can be a tool. Keep them:\n- **Atomic** - Do one thing well\n- **Typed** - Use type hints for parameters\n- **Documented** - Docstrings help the LLM understand usage\n\n## Status\n\n**BETA** - Actively developed and used in production. Breaking changes possible until v1.0.\n\nFound a bug? Have a feature request? [Open an issue](https://github.com/alchemiststudiosDOTai/tinyAgent/issues)!\n\n## License\n\n**Business Source License 1.1**\n- Free for individuals and small businesses (< $1M revenue)\n- Enterprise license required for larger companies\n\nContact: [info@alchemiststudios.ai](mailto:info@alchemiststudios.ai)\n\n---\n\nMade by [@tunahorse21](https://x.com/tunahorse21) | [alchemiststudios.ai](https://alchemiststudios.ai) focusing on keeping it \"tiny\"\n",
"bugtrack_url": null,
"license": "Business Source License 1.1",
"summary": "A streamlined framework for building powerful LLM-powered agents that actually work",
"version": "0.73.1",
"project_urls": {
"Homepage": "https://tinyagent.xyz",
"Issues": "https://github.com/alchemiststudiosDOTai/tinyAgent/issues",
"Repository": "https://github.com/alchemiststudiosDOTai/tinyAgent"
},
"split_keywords": [
"ai",
" agent",
" llm",
" openai",
" gpt",
" react"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b97ba8707ff6d14ea1458dd9abb84928a17dbaf07567fe12fa9d9f17c7f1b1fc",
"md5": "09a3783dc51c8e63966cbc9521826438",
"sha256": "b6c48f868bc151a62304b25c11b293a8466e1953de233b4c993b4a9d85d3ecaf"
},
"downloads": -1,
"filename": "tiny_agent_os-0.73.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "09a3783dc51c8e63966cbc9521826438",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14581,
"upload_time": "2025-08-15T19:23:43",
"upload_time_iso_8601": "2025-08-15T19:23:43.494458Z",
"url": "https://files.pythonhosted.org/packages/b9/7b/a8707ff6d14ea1458dd9abb84928a17dbaf07567fe12fa9d9f17c7f1b1fc/tiny_agent_os-0.73.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c12f25121b1b6466aadaca52ed5010673fe9e6255735ef0c88209a175fd40332",
"md5": "329766e4623041050a5015d37f809377",
"sha256": "01a4ab8f3509dc3fc7f603c254841de8a0856419f22b760331803d197d5233a1"
},
"downloads": -1,
"filename": "tiny_agent_os-0.73.1.tar.gz",
"has_sig": false,
"md5_digest": "329766e4623041050a5015d37f809377",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 61697,
"upload_time": "2025-08-15T19:23:44",
"upload_time_iso_8601": "2025-08-15T19:23:44.693054Z",
"url": "https://files.pythonhosted.org/packages/c1/2f/25121b1b6466aadaca52ed5010673fe9e6255735ef0c88209a175fd40332/tiny_agent_os-0.73.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 19:23:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alchemiststudiosDOTai",
"github_project": "tinyAgent",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tiny-agent-os"
}
JSON
