TinyAgent

Quick Links

Live Projects using TinyAgent (🔥)

🚀 The Vision: Your AI, Your Choice, Your Rules

🎯 Why TinyAgent Changes Everything

What's new for developers

Installation

Using pip

# Basic installation
pip install tinyagent-py
# Install with all optional dependencies
pip install tinyagent-py[all]
# Install with Code Agent support
pip install tinyagent-py[code]
# Install with PostgreSQL support
pip install tinyagent-py[postgres]
# Install with SQLite support
pip install tinyagent-py[sqlite]
# Install with Gradio UI support
pip install tinyagent-py[gradio]

Using uv

# Basic installation
uv pip install tinyagent-py
# Install with Code Agent support
uv pip install tinyagent-py[code]
# Install with PostgreSQL support
uv pip install tinyagent-py[postgres]
# Install with SQLite support
uv pip install tinyagent-py[sqlite]
# Install with Gradio UI support
uv pip install tinyagent-py[gradio]
# Install with all optional dependencies
uv pip install tinyagent-py[all]

Developer Boilerplate & Quick Start

OpenAI Responses API (optional)

export TINYAGENT_LLM_API=responses

import os
import asyncio
from tinyagent import TinyAgent
async def main():
 # Option A: via environment variable
 os.environ["TINYAGENT_LLM_API"] = "responses" # or "chat" (default)
 agent = await TinyAgent.create(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 # Option B: programmatic preference via model_kwargs
 model_kwargs={"llm_api": "responses"}, # or {"use_responses_api": True}
 )
 print(await agent.run("List three safe git commands for a repo"))
asyncio.run(main())

🚀 TinyAgent with New Tools

import asyncio
import os
from tinyagent import TinyAgent
from tinyagent.tools.subagent import create_general_subagent
async def create_enhanced_tinyagent():
 """Create a TinyAgent with all new tools and capabilities."""
 
 # Initialize TinyAgent (TodoWrite is enabled by default)
 agent = TinyAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 enable_todo_write=True # Enable TodoWrite tool (True by default)
 )
 
 # Add a general-purpose subagent for parallel tasks
 helper_subagent = create_general_subagent(
 name="helper",
 model="gpt-5-mini",
 max_turns=20,
 enable_python=True,
 enable_shell=True
 )
 agent.add_tool(helper_subagent)
 
 # Check available tools
 available_tools = list(agent.custom_tool_handlers.keys())
 print(f"Available tools: {available_tools}") # ['TodoWrite', 'helper']
 
 # Connect to MCP servers for extended functionality
 await agent.connect_to_server("npx", ["@openbnb/mcp-server-airbnb", "--ignore-robots-txt"])
 
 return agent
async def main():
 agent = await create_enhanced_tinyagent()
 
 try:
 # Example: Complex task with subagent delegation
 result = await agent.run("""
 I need help with a travel planning project:
 1. Create a todo list for this task
 2. Use the helper subagent to find 5 accommodations in Paris for December 2024
 3. Research transportation options between airports and city center
 4. Organize all findings into a structured report

 Make sure to track progress with the todo system.
 """)
 
 print("Result:", result)
 finally:
 await agent.close()
# Run the example
asyncio.run(main())

🛠️ TinyCodeAgent with File Tools & Providers

import asyncio
import os
from tinyagent import TinyCodeAgent
from tinyagent.hooks.rich_code_ui_callback import RichCodeUICallback
async def create_enhanced_code_agent():
 """Create TinyCodeAgent with all file tools and provider features."""
 
 # Option 1: Using Seatbelt Provider (macOS sandbox)
 seatbelt_agent = TinyCodeAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 provider="seatbelt",
 provider_config={
 "python_env_path": "/usr/local/bin/python3",
 "additional_read_dirs": ["/Users/username/projects"],
 "additional_write_dirs": ["/Users/username/projects/output"],
 "environment_variables": {"PROJECT_ROOT": "/Users/username/projects"}
 },
 # Enable all new tools
 enable_python_tool=True,
 enable_shell_tool=True, 
 enable_file_tools=True,
 enable_todo_write=True,
 # REQUIRED: Local execution for Seatbelt provider
 local_execution=True,
 # Working directory for operations
 default_workdir="/Users/username/projects",
 # Auto git checkpoints after shell commands
 auto_git_checkpoint=True,
 # Rich UI for better visualization
 ui="rich",
 # Debug mode control (default: False)
 debug_mode=False # Set to True to see command execution details
 )
 
 return seatbelt_agent
async def create_modal_code_agent():
 """Create TinyCodeAgent with Modal.com provider."""
 
 modal_agent = TinyCodeAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 provider="modal",
 provider_config={
 "pip_packages": ["requests", "pandas", "matplotlib", "seaborn"]
 },
 authorized_imports=["requests", "pandas", "matplotlib", "seaborn", "numpy"],
 enable_python_tool=True,
 enable_shell_tool=True,
 enable_file_tools=True,
 enable_todo_write=True,
 local_execution=False, # Use Modal cloud execution
 truncation_config={
 "max_tokens": 5000,
 "max_lines": 300,
 "enabled": True
 }
 )
 
 return modal_agent
async def demonstrate_file_tools():
 """Demonstrate the new file tools functionality."""
 
 agent = await create_enhanced_code_agent()
 
 try:
 # Check available tools
 available_tools = list(agent.custom_tool_handlers.keys())
 print(f"Available tools: {available_tools}")
 
 result = await agent.run("""
 I need to analyze a Python project structure:

 1. Use glob to find all Python files in the current directory
 2. Use grep to search for "class" definitions across all Python files
 3. Read the main configuration file if it exists
 4. Create a summary report of the project structure
 5. Track progress with todos

 Make sure to use the new file tools for secure operations.
 """)
 
 print("Analysis Result:", result)
 
 finally:
 await agent.close()
# Choose your provider
async def main():
 print("Demonstrating TinyCodeAgent with enhanced file tools...")
 await demonstrate_file_tools()
asyncio.run(main())

📁 File Tools Usage Examples

import asyncio
from tinyagent import TinyCodeAgent
async def file_tools_examples():
 """Examples of using the new sandboxed file tools."""
 
 agent = TinyCodeAgent(
 model="gpt-4o-mini",
 local_execution=True, # Auto-selects best provider
 enable_file_tools=True
 )
 
 try:
 # Check available tools
 available_tools = list(agent.custom_tool_handlers.keys())
 print(f"Available file tools: {available_tools}")
 
 # Example 1: Project structure analysis
 await agent.run("""
 Use glob to find all Python files in this project:
 - Pattern: "**/*.py" 
 - Search in: "/Users/username/myproject"

 Then use grep to find all function definitions:
 - Pattern: "def "
 - Search in the same directory

 Finally, read the main.py file to understand the entry point.
 """)
 
 # Example 2: Safe file modification
 await agent.run("""
 I need to update a configuration file:
 1. Read config.json to see current settings
 2. Update the database URL using update_file tool
 3. Verify the changes were applied correctly

 Make sure to use exact string matching for safety.
 """)
 
 # Example 3: Code generation and file creation
 await agent.run("""
 Create a new Python module:
 1. Use write_file to create utils/helpers.py
 2. Add utility functions for string manipulation
 3. Include proper docstrings and type hints
 4. Create a simple test file for the utilities
 """)
 
 finally:
 await agent.close()
asyncio.run(file_tools_examples())

🔧 Grep and Glob Tool Examples

# Glob tool examples
await agent.run("""
Find all JavaScript files in the frontend directory:
Use glob with pattern "**/*.{js,jsx}" in "/path/to/frontend"
""")
await agent.run("""
Find all markdown documentation:
Use glob with pattern "**/*.md" in "/path/to/project"
""")
# Grep tool examples 
await agent.run("""
Search for all TODO comments in the codebase:
Use grep with pattern "TODO|FIXME|XXX" and regex=True
Search in "/path/to/project" directory
Use output_mode="content" to see the actual lines
""")
await agent.run("""
Find all API endpoints in Python files:
Use grep with pattern "@app.route" 
Search only in Python files using glob="**/*.py"
""")

📋 TodoWrite Tool Integration

import asyncio
from tinyagent import TinyAgent
from tinyagent.tools.todo_write import get_current_todos, get_todo_summary
async def todo_workflow_example():
 """Example of using TodoWrite for task management."""
 
 agent = TinyAgent(
 model="gpt-5-mini",
 enable_todo_write=True # Enabled by default
 )
 
 try:
 # Check that TodoWrite tool is available
 available_tools = list(agent.custom_tool_handlers.keys())
 print(f"Available tools: {available_tools}") # Should include 'TodoWrite'
 
 # The agent can automatically use TodoWrite during complex tasks
 result = await agent.run("""
 I need to build a web scraping system:
 1. Create a todo list for this project
 2. Research the target website structure
 3. Implement the scraping logic with error handling
 4. Add data validation and cleaning
 5. Create output formatting and export functions
 6. Write tests for each component
 7. Update todos as you progress

 Use the TodoWrite tool to track all these steps.
 """)
 
 # Check current todos programmatically
 current_todos = get_current_todos()
 summary = get_todo_summary()
 
 print(f"Project Status: {summary}")
 print(f"Active Todos: {len(current_todos)}")
 
 finally:
 await agent.close()
asyncio.run(todo_workflow_example())

🐛 Debug Mode Control

import asyncio
import os
from tinyagent import TinyCodeAgent
async def debug_mode_examples():
 """Examples of debug mode control for TinyCodeAgent."""
 
 # Production mode: Clean output (default)
 production_agent = TinyCodeAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 provider="seatbelt",
 local_execution=True,
 debug_mode=False # Default: No debug prints
 )
 
 # Development mode: Show execution details 
 debug_agent = TinyCodeAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 provider="seatbelt", 
 local_execution=True,
 debug_mode=True # Shows command execution details
 )
 
 # Environment variable control (overrides constructor)
 os.environ['TINYAGENT_DEBUG_MODE'] = '1' # Enable globally
 env_agent = TinyCodeAgent(
 model="gpt-5-mini",
 provider="seatbelt",
 local_execution=True
 # debug_mode will be True due to environment variable
 )
 
 try:
 # Production agent: Clean output
 print("=== Production Mode (Clean Output) ===")
 await production_agent.run("Run: echo 'Hello Production'")
 
 # Debug agent: Detailed output with command traces
 print("\n=== Debug Mode (Detailed Output) ===") 
 await debug_agent.run("Run: echo 'Hello Debug'")
 
 finally:
 await production_agent.close()
 await debug_agent.close()
 await env_agent.close()
asyncio.run(debug_mode_examples())

# Enable debug mode globally
export TINYAGENT_DEBUG_MODE=1 # or 'true', 'yes', 'on'
# Disable debug mode globally 
export TINYAGENT_DEBUG_MODE=0 # or 'false', 'no', 'off'
# Unset to use constructor parameter
unset TINYAGENT_DEBUG_MODE

🔒 Universal Tool Control with Hooks

import asyncio
from tinyagent import TinyCodeAgent
from tinyagent.code_agent.tools.file_tools import FileOperationApprovalHook, ProductionApprovalHook
class CustomFileHook(FileOperationApprovalHook):
 """Custom hook for file operation control."""
 
 async def before_tool_execution(self, event_name: str, agent, **kwargs):
 tool_name = kwargs.get("tool_name")
 tool_args = kwargs.get("tool_args", {})
 
 # Custom logic for file operations
 if tool_name in ["write_file", "update_file"]:
 file_path = tool_args.get("file_path", "")
 
 # Block operations on sensitive files
 if "secret" in file_path.lower() or "password" in file_path.lower():
 print(f"🚫 Blocked file operation on sensitive file: {file_path}")
 return {"proceed": False, "reason": "Sensitive file access denied"}
 
 # Log all file modifications
 print(f"📝 File operation: {tool_name} on {file_path}")
 
 return {"proceed": True}
async def controlled_agent_example():
 """Example of agent with file operation controls."""
 
 agent = TinyCodeAgent(
 model="gpt-5-mini", 
 provider="seatbelt",
 enable_file_tools=True
 )
 
 # Add custom file control hook
 file_hook = CustomFileHook(auto_approve=False)
 agent.add_callback(file_hook)
 
 try:
 await agent.run("""
 Analyze and modify some project files:
 1. Read the main application file
 2. Update version information in package.json
 3. Create a backup of important configuration

 The system will control which operations are allowed.
 """)
 
 finally:
 await agent.close()
asyncio.run(controlled_agent_example())

📚 Complete Examples Collection

Using Local Models with Ollama

Prerequisites

Basic Usage with Ollama

import asyncio
from tinyagent import TinyAgent
async def main():
 # Initialize TinyAgent with Ollama model
 # Format: "ollama/<model-name>"
 agent = TinyAgent(
 model="ollama/qwen2.5-coder:7b", # or "ollama/codellama", "ollama/mixtral", etc.
 api_key=None, # No API key needed for local models
 temperature=0.7,
 system_prompt="You are a helpful AI assistant running locally."
 )
 
 try:
 # Connect to MCP servers if needed
 await agent.connect_to_server("npx", ["@openbnb/mcp-server-airbnb", "--ignore-robots-txt"])
 
 # Run the agent
 result = await agent.run("What can you help me with today?")
 print("Response:", result)
 finally:
 await agent.close()
asyncio.run(main())

TinyCodeAgent with Ollama

import asyncio
from tinyagent import TinyCodeAgent
async def main():
 # Use code-optimized models for better results
 agent = TinyCodeAgent(
 model="ollama/qwen2.5-coder:7b", # qwen2.5-coder:7b is optimized for code tasks
 api_key=None,
 provider="seatbelt", # or "modal" for cloud execution
 enable_python_tool=True,
 enable_shell_tool=True,
 enable_file_tools=True
 )
 
 try:
 result = await agent.run("""
 Write a Python function to calculate fibonacci numbers
 and test it with the first 10 numbers.
 """)
 print("Result:", result)
 finally:
 await agent.close()
asyncio.run(main())

Advanced Ollama Configuration

from tinyagent import TinyAgent
# Custom Ollama endpoint (if not using default)
agent = TinyAgent(
 model="ollama/llama2",
 api_key=None,
 model_kwargs={
 "api_base": "http://localhost:11434", # Custom Ollama server
 "num_predict": 2048, # Max tokens to generate
 "top_k": 40,
 "top_p": 0.9,
 "repeat_penalty": 1.1
 }
)
# Using with hooks and callbacks
from tinyagent.hooks.rich_ui_callback import RichUICallback
agent = TinyAgent(
 model="ollama/mixtral",
 api_key=None,
 temperature=0.5
)
# Add rich UI for better visualization
ui = RichUICallback()
agent.add_callback(ui)

Recommended Ollama Models

Performance Tips

Custom Instructions System 📝

Key Features

Quick Start

Basic Usage with String Instructions

import asyncio
from tinyagent import TinyAgent
async def main():
 # Add custom instructions directly as a string
 custom_instructions = """
 You are working on a Python web application project.
 Always consider:
 - Security best practices
 - Performance implications
 - Code maintainability
 - Follow PEP 8 style guidelines
 """
 
 agent = TinyAgent(
 model="gpt-5-mini",
 api_key="your-api-key",
 custom_instruction=custom_instructions,
 enable_custom_instruction=True
 )
 
 result = await agent.run("Help me refactor this Django view function")
 print(result)
asyncio.run(main())

Automatic AGENTS.md Loading

# Project Instructions for AI Agents
You are assisting with the TinyAgent Python framework project.
## Context
- This is an AI agent framework focused on modularity and extensibility
- Code should follow Python best practices and be well-documented
- Always consider backward compatibility when making changes
## Coding Standards
- Use type hints consistently
- Write comprehensive docstrings
- Add appropriate error handling
- Follow the existing project structure
## Testing Requirements
- Write unit tests for new functionality
- Use pytest for testing
- Maintain test coverage above 80%

from tinyagent import TinyAgent
# Will automatically load AGENTS.md if present in current directory
agent = TinyAgent(
 model="gpt-5-mini",
 api_key="your-api-key",
 enable_custom_instruction=True, # Enable auto-loading (default: True)
 custom_instruction_file="AGENTS.md" # Default filename
)

Custom File Locations

from tinyagent import TinyCodeAgent
# Use custom instruction file from different location
agent = TinyCodeAgent(
 model="gpt-5-mini",
 provider="seatbelt",
 enable_custom_instruction=True,
 custom_instruction_file="config/my_agent_instructions.md",
 custom_instruction_directory="/path/to/project"
)

Advanced Configuration

Custom Placeholder Support

# Custom system prompt with placeholder
custom_prompt = """
You are a helpful AI assistant.

<user_specified_instruction></user_specified_instruction>

Always be concise and helpful.
"""
agent = TinyAgent(
 model="gpt-5-mini",
 system_prompt=custom_prompt,
 custom_instruction="Focus on Python development best practices.",
 enable_custom_instruction=True
)

Runtime Configuration

from tinyagent import TinyAgent
agent = TinyAgent(
 model="gpt-5-mini",
 # Custom instruction configuration
 enable_custom_instruction=True,
 custom_instruction="Initial instructions here",
 custom_instruction_file="AGENTS.md",
 custom_instruction_directory="./config",
 custom_instruction_placeholder="<custom_guidance></custom_guidance>",
 custom_instruction_subagent_inheritance=True
)
# Update instructions at runtime
agent.set_custom_instruction("Updated project guidelines")
# Reload from file
agent.reload_custom_instruction()
# Disable/enable dynamically
agent.enable_custom_instruction(False) # Disable
agent.enable_custom_instruction(True) # Re-enable

TinyCodeAgent Integration

from tinyagent import TinyCodeAgent
# Project-specific coding instructions
coding_instructions = """
## Code Execution Guidelines
- Always validate input parameters
- Use secure coding practices
- Implement proper error handling
- Write self-documenting code with clear variable names

## Project Context
- Working with financial data - be extra careful with calculations
- All monetary values should use Decimal type
- Log all significant operations for audit trail
"""
agent = TinyCodeAgent(
 model="gpt-5-mini",
 provider="modal",
 custom_instruction=coding_instructions,
 enable_custom_instruction=True,
 enable_python_tool=True,
 enable_shell_tool=True
)

Subagent Inheritance Control

from tinyagent import TinyAgent
from tinyagent.tools.subagent import create_general_subagent
# Main agent with project instructions
main_agent = TinyAgent(
 model="gpt-5-mini",
 custom_instruction="Main project guidelines",
 enable_custom_instruction=True,
 custom_instruction_subagent_inheritance=True # Subagents will inherit
)
# Create subagent - will automatically inherit custom instructions
helper = create_general_subagent(
 name="helper",
 model="gpt-5-mini",
 max_turns=15
)
main_agent.add_tool(helper)
# For selective inheritance control
specific_agent = TinyAgent(
 model="gpt-5-mini",
 custom_instruction="Specialized guidelines for this agent only",
 custom_instruction_subagent_inheritance=False # Don't pass to subagents
)

File Format Support

Markdown Format (Recommended)

# Agent Instructions
## Project Context
Brief description of the project and its goals.
## Guidelines
- Specific behaviors and preferences
- Technical requirements
- Quality standards
## Examples
Code examples or usage patterns to follow.

Plain Text Format

Project: E-commerce Platform Development
Guidelines:
- Follow REST API best practices
- Use proper HTTP status codes
- Implement comprehensive error handling
- Write OpenAPI documentation for all endpoints
Security Requirements:
- Always validate and sanitize input
- Implement proper authentication checks
- Use parameterized queries for database access

Logging and Warnings

import logging
from tinyagent import TinyAgent
# Enable debug logging to see custom instruction loading
logging.basicConfig(level=logging.DEBUG)
agent = TinyAgent(
 model="gpt-5-mini",
 enable_custom_instruction=True,
 custom_instruction_file="AGENTS.md"
)
# Log messages you'll see:
# INFO: Custom instruction loaded from AGENTS.md (1234 characters)
# WARNING: Custom instruction is enabled but AGENTS.md file not found
# INFO: Custom instruction disabled, ignoring AGENTS.md file

Configuration Options Reference

Best Practices

Common Use Cases

Error Handling

# File not found - logs warning and continues
agent = TinyAgent(
 model="gpt-5-mini",
 enable_custom_instruction=True,
 custom_instruction_file="missing_file.md"
)
# WARNING: Custom instruction file not found: missing_file.md
# Invalid file path - falls back to string interpretation
agent = TinyAgent(
 model="gpt-5-mini", 
 custom_instruction="/invalid/path/instructions.md"
)
# INFO: Treating custom_instruction as direct string content
# Empty or malformed files - logs warning
# WARNING: Custom instruction file is empty or unreadable

Session Persistence with Storage

Available Storage Systems

SQLite Storage Example

import asyncio
import os
from tinyagent import TinyAgent
from tinyagent.storage.sqlite_storage import SqliteStorage
async def persistent_agent_example():
 """Example showing how to use SQLite storage for session persistence."""
 
 # Initialize SQLite storage
 # This will create a local database file to store sessions
 storage = SqliteStorage(
 db_path="./agent_sessions.db", # Local SQLite database file
 table_name="tny_agent_sessions" # Custom table name (optional)
 )
 
 # Create agent with persistent storage
 # If session_id exists, it will resume the previous conversation
 agent = TinyAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 session_id="user-123-chat", # Unique session identifier
 user_id="user-123", # Optional user identifier
 storage=storage, # Enable persistent storage
 temperature=1.0,
 metadata={
 "user_name": "Alice",
 "application": "customer-support",
 "version": "1.0"
 }
 )
 
 try:
 # First run - will create new session or resume existing one
 print("=== First Interaction ===")
 result1 = await agent.run("Hello! My name is Alice. What can you help me with?")
 print(f"Agent: {result1}")
 
 # Second run - state is automatically persisted
 print("\n=== Second Interaction ===")
 result2 = await agent.run("Do you remember my name from our previous conversation?")
 print(f"Agent: {result2}")
 
 # Check current conversation length
 print(f"\nConversation has {len(agent.messages)} messages")
 
 # You can also manually save at any point
 await agent.save_agent()
 print("Session manually saved!")
 
 finally:
 # Clean up resources
 await agent.close()
# Run the example
asyncio.run(persistent_agent_example())

Resuming Sessions

import asyncio
from tinyagent import TinyAgent
from tinyagent.storage.sqlite_storage import SqliteStorage
async def resume_session_example():
 """Example showing how to resume a previous session."""
 
 storage = SqliteStorage(db_path="./agent_sessions.db")
 
 # Resume existing session
 agent = TinyAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 session_id="user-123-chat", # Same session ID as before
 user_id="user-123",
 storage=storage
 )
 
 # Load the existing session
 await agent.init_async()
 
 try:
 # This will continue from where the previous conversation left off
 print(f"Resumed session with {len(agent.messages)} previous messages")
 
 result = await agent.run("Can you summarize our conversation so far?")
 print(f"Agent: {result}")
 
 finally:
 await agent.close()
asyncio.run(resume_session_example())

Multiple User Sessions

import asyncio
from tinyagent import TinyAgent
from tinyagent.storage.sqlite_storage import SqliteStorage
async def multi_user_example():
 """Example showing multiple user sessions."""
 
 storage = SqliteStorage(db_path="./multi_user_sessions.db")
 
 # User 1 session
 agent1 = TinyAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 session_id="chat-session-1",
 user_id="user-alice",
 storage=storage,
 temperature=1.0,
 metadata={"user_name": "Alice", "role": "developer"}
 )
 
 # User 2 session 
 agent2 = TinyAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"), 
 session_id="chat-session-2",
 user_id="user-bob",
 storage=storage,
 temperature=1.0,
 metadata={"user_name": "Bob", "role": "manager"}
 )
 
 try:
 # Each user gets their own isolated conversation
 result1 = await agent1.run("Hi, I'm Alice and I'm working on a Python project.")
 result2 = await agent2.run("Hello, I'm Bob and I need help with project management.")
 
 print(f"Alice's agent: {result1}")
 print(f"Bob's agent: {result2}")
 
 finally:
 await agent1.close()
 await agent2.close()
asyncio.run(multi_user_example())

Advanced Storage Configuration

import asyncio
from tinyagent import TinyAgent
from tinyagent.storage.sqlite_storage import SqliteStorage
from tinyagent.hooks.rich_ui_callback import RichUICallback
async def advanced_storage_example():
 """Advanced example with custom storage configuration."""
 
 # Initialize storage with custom table name and path
 storage = SqliteStorage(
 db_path="./data/conversations/agent.db", # Custom path (directories will be created)
 table_name="custom_sessions" # Custom table name
 )
 
 # Create agent with comprehensive configuration
 agent = TinyAgent(
 model="gpt-5-mini",
 api_key=os.getenv("OPENAI_API_KEY"),
 session_id="advanced-session",
 user_id="power-user",
 storage=storage,
 
 # Additional configuration
 metadata={
 "application": "ai-assistant",
 "version": "2.0",
 "user_tier": "premium",
 "features": ["code_execution", "file_access"]
 },
 
 # Enable tool persistence (experimental)
 persist_tool_configs=True,
 
 # Add conversation summarization for long sessions
 summary_config={
 "model": "gpt-5-mini",
 "max_messages": 50, # Summarize when over 50 messages
 "system_prompt": "Provide a concise summary of this conversation."
 }
 )
 
 # Add rich UI for better visualization
 ui = RichUICallback(show_thinking=True, show_tool_calls=True)
 agent.add_callback(ui)
 
 try:
 # Connect to tools/services
 await agent.connect_to_server("npx", ["@openbnb/mcp-server-airbnb", "--ignore-robots-txt"])
 
 # Run agent with complex task
 result = await agent.run("""
 I'm planning a trip to Tokyo. Can you help me:
 1. Find 3 good accommodation options
 2. Research local transportation
 3. Suggest must-visit attractions
 4. Create a 3-day itinerary

 Keep track of all this information for our future conversations.
 """)
 
 print(f"Result: {result}")
 
 # Check storage metadata
 print(f"\nSession metadata: {agent.metadata}")
 print(f"Messages in conversation: {len(agent.messages)}")
 
 finally:
 await agent.close()
asyncio.run(advanced_storage_example())

Storage Installation Requirements

# SQLite (included with Python, no extra installation needed)
pip install tinyagent-py[sqlite]
# PostgreSQL
pip install tinyagent-py[postgres]
# Redis 
pip install tinyagent-py[redis]
# All storage backends
pip install tinyagent-py[all]

Best Practices for Storage

Usage

TinyAgent (Core Agent)

from tinyagent import TinyAgent
from textwrap import dedent
import asyncio
import os
async def test_agent(task, model="gpt-5-mini", api_key=None):
 # Initialize the agent with model and API key
 agent = TinyAgent(
 model=model, # Or any model supported by LiteLLM
 api_key=os.environ.get("OPENAI_API_KEY") if not api_key else api_key # Set your API key as an env variable
 )
 
 try:
 # Connect to an MCP server
 # Replace with your actual server command and args
 await agent.connect_to_server("npx", ["@openbnb/mcp-server-airbnb", "--ignore-robots-txt"])
 
 # Run the agent with a user query
 result = await agent.run(task)
 print("\nFinal result:", result)
 return result
 finally:
 # Clean up resources
 await agent.close()
# Example usage
task = dedent("""
I need accommodation in Toronto between 15th to 20th of May. Give me 5 options for 2 adults.
""")
await test_agent(task, model="gpt-5-mini")

🔌 MCP (Model Context Protocol) Integration

🚀 Quick MCP Connection

import asyncio
from tinyagent import TinyAgent
async def basic_mcp_example():
 agent = TinyAgent(model="gpt-5-mini")
 try:
 # Connect to an MCP server (STDIO transport)
 await agent.connect_to_server(
 command="npx",
 args=["@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
 )
 result = await agent.run("Find me hotels in Tokyo for 2 adults")
 print(result)
 finally:
 await agent.close()
asyncio.run(basic_mcp_example())

🎯 Progress Callback Support

Default Progress Callback (Recommended)

import asyncio
from tinyagent import TinyAgent
async def progress_example():
 agent = TinyAgent(model="gpt-5-mini")
 try:
 # Enable default progress callback (logs to agent's logger + stdout)
 await agent.connect_to_server(
 command="python",
 args=["my_slow_mcp_server.py"],
 enable_default_progress_callback=True
 )
 # Progress updates will be automatically logged during tool execution
 result = await agent.run("Process this large dataset")
 print(result)
 finally:
 await agent.close()
asyncio.run(progress_example())

Custom Progress Callback

import asyncio
from tinyagent import TinyAgent
class ProgressTracker:
 def __init__(self, name: str):
 self.name = name
 self.updates = []
 async def __call__(self, progress: float, total: float = None, message: str = None):
 """Custom progress callback function."""
 self.updates.append({"progress": progress, "total": total, "message": message})
 if total and total > 0:
 percentage = (progress / total) * 100
 print(f"🔄 {self.name}: [{percentage:5.1f}%] {message}")
 else:
 print(f"🔄 {self.name}: [Step {progress}] {message}")
async def custom_progress_example():
 agent = TinyAgent(model="gpt-5-mini")
 tracker = ProgressTracker("Data Processing")
 try:
 # Use custom progress callback
 await agent.connect_to_server(
 command="python",
 args=["my_mcp_server.py"],
 progress_callback=tracker
 )
 result = await agent.run("Analyze this complex dataset")
 print(f"Completed with {len(tracker.updates)} progress updates")
 finally:
 await agent.close()
asyncio.run(custom_progress_example())

🌐 MCP Transport Types

1. STDIO Transport (Default)

# STDIO transport (default)
await agent.connect_to_server(
 command="python",
 args=["mcp_server.py"],
 env={"API_KEY": "your-key"} # Optional environment variables
)
# Node.js MCP server
await agent.connect_to_server(
 command="npx",
 args=["@modelcontextprotocol/server-filesystem", "/tmp"]
)
# Python MCP server with arguments
await agent.connect_to_server(
 command="python",
 args=["-m", "my_mcp_package", "--config", "production.yaml"]
)

2. SSE (Server-Sent Events) Transport

from tinyagent.mcp_client import MCPServerConfig
# SSE transport configuration
config = MCPServerConfig(
 name="web_mcp_server",
 transport="sse",
 sse_url="http://localhost:3000/mcp",
 headers={"Authorization": "Bearer your-token"},
 timeout=120.0
)
# Connect using TinyMultiMCPTools directly for SSE
from tinyagent.mcp_client import TinyMultiMCPTools
async def sse_example():
 agent = TinyAgent(model="gpt-5-mini")
 async with TinyMultiMCPTools([config], agent.logger) as multi_mcp:
 # Use SSE-connected tools
 result = await multi_mcp.call_tool(
 tool_name="web_search",
 arguments={"query": "latest AI news"}
 )
 print(result)
asyncio.run(sse_example())

3. HTTP Transport

# HTTP transport configuration
config = MCPServerConfig(
 name="rest_mcp_server",
 transport="http",
 http_base_url="https://api.example.com/mcp",
 headers={
 "Authorization": "Bearer your-api-token",
 "Content-Type": "application/json"
 },
 timeout=60.0
)
async def http_example():
 agent = TinyAgent(model="gpt-5-mini")
 async with TinyMultiMCPTools([config], agent.logger) as multi_mcp:
 result = await multi_mcp.call_tool(
 tool_name="process_data",
 arguments={"input": "user data"}
 )
 print(result)
asyncio.run(http_example())

🔄 Multiple MCP Servers

import asyncio
from tinyagent import TinyAgent
async def multi_server_example():
 agent = TinyAgent(model="gpt-5-mini")
 try:
 # Connect to multiple servers
 await agent.connect_to_server(
 command="npx",
 args=["@openbnb/mcp-server-airbnb"],
 enable_default_progress_callback=True
 )
 await agent.connect_to_server(
 command="python",
 args=["weather_mcp_server.py"],
 progress_callback=custom_tracker
 )
 await agent.connect_to_server(
 command="node",
 args=["travel_mcp_server.js"]
 )
 # All servers' tools are now available
 result = await agent.run("""
 Plan a trip to Tokyo:
 1. Check the weather forecast
 2. Find accommodation options
 3. Suggest travel routes
 """)
 print(result)
 finally:
 await agent.close()
asyncio.run(multi_server_example())

🛠️ Advanced MCP Configuration

Tool Filtering

# Include only specific tools
await agent.connect_to_server(
 command="python",
 args=["comprehensive_mcp_server.py"],
 include_tools=["search", "analyze", "export"], # Only these tools
 enable_default_progress_callback=True
)
# Exclude specific tools
await agent.connect_to_server(
 command="python",
 args=["mcp_server.py"],
 exclude_tools=["delete", "admin"], # Skip these tools
 progress_callback=tracker
)

Environment Variables

await agent.connect_to_server(
 command="python",
 args=["configurable_mcp_server.py"],
 env={
 "API_BASE_URL": "https://api.production.com",
 "API_KEY": os.getenv("PRODUCTION_API_KEY"),
 "LOG_LEVEL": "INFO",
 "RATE_LIMIT": "1000"
 },
 enable_default_progress_callback=True
)

📊 Progress Callback Features

🚨 Error Handling & Best Practices

import asyncio
import logging
from tinyagent import TinyAgent
async def robust_mcp_example():
 agent = TinyAgent(model="gpt-5-mini")
 try:
 # Configure with timeouts and error handling
 await agent.connect_to_server(
 command="python",
 args=["reliable_mcp_server.py"],
 enable_default_progress_callback=True,
 env={"TIMEOUT": "300"} # 5 minute timeout
 )
 # Handle potential tool failures gracefully
 result = await agent.run("""
 Process this data with error handling:
 1. Validate input data
 2. Process with retry logic
 3. Export results with verification
 """)
 except Exception as e:
 logging.error(f"MCP operation failed: {e}")
 # Implement fallback logic
 result = "Operation failed, using fallback approach"
 finally:
 await agent.close()
asyncio.run(robust_mcp_example())

🔒 Cross-Platform Sandboxing & Security

🌍 Universal Provider Support

🚀 Quick Setup Examples

Zero Configuration (Recommended)

from tinyagent import TinyCodeAgent
# Automatically selects best provider for your platform
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 local_execution=True # Auto: macOS→Seatbelt, Linux→Bubblewrap, Windows→Docker
)
result = await agent.execute_python(["print('Hello from secure sandbox!')"])

Explicit Provider Selection

# Force Docker (works everywhere)
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="docker",
 provider_config={
 "memory_limit": "1g",
 "enable_network": False,
 "environment_variables": {"PROJECT_ROOT": "/workspace"}
 }
)
# Platform-specific with fallback
agent = TinyCodeAgent(
 model="gpt-4o-mini", 
 provider="bubblewrap", # Try Linux native first
 provider_fallback=True, # Fall back to docker if unavailable
 local_execution=True
)

📋 Platform-Specific Setup Instructions

🍎 macOS - SeatbeltProvider (Native)

from tinyagent import TinyCodeAgent
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="seatbelt",
 provider_config={
 "python_env_path": "/usr/local/bin/python3",
 "additional_read_dirs": ["/Users/username/projects"],
 "additional_write_dirs": ["/Users/username/projects/output"],
 "environment_variables": {
 "PROJECT_ROOT": "/Users/username/projects",
 "GITHUB_TOKEN": "your-token" # For git operations
 },
 "bypass_shell_safety": True # Enable shell commands
 },
 local_execution=True # Required for seatbelt
)

# Verify seatbelt is available
which sandbox-exec
# Should return: /usr/bin/sandbox-exec
# Test basic sandboxing
sandbox-exec -f /usr/share/sandbox/pure.sb echo "Hello Sandbox"

🐧 Linux - BubblewrapProvider (Native)

# Ubuntu/Debian
sudo apt update && sudo apt install bubblewrap
# CentOS/RHEL/Fedora
sudo dnf install bubblewrap
# or: sudo yum install bubblewrap
# Alpine Linux
sudo apk add bubblewrap
# Arch Linux
sudo pacman -S bubblewrap

from tinyagent import TinyCodeAgent
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="bubblewrap",
 provider_config={
 "additional_read_dirs": ["/home/user/projects"],
 "additional_write_dirs": ["/home/user/projects/output"],
 "environment_variables": {
 "PROJECT_ROOT": "/home/user/projects",
 "GITHUB_USERNAME": "username",
 "GITHUB_TOKEN": "your-token"
 },
 "bypass_shell_safety": False # Enable security checks
 },
 local_execution=True # Required for bubblewrap
)

# Verify bubblewrap installation
bwrap --version
# Should show version info
# Test basic sandboxing
bwrap --ro-bind / / --dev /dev --proc /proc --tmpfs /tmp echo "Hello Bubblewrap"
# Verify user namespaces are enabled
cat /proc/sys/kernel/unprivileged_userns_clone
# Should return: 1

# Use our pre-built Docker testing infrastructure
cd /path/to/tinyagent
git clone <repo-url> && cd tinyagent/docker-testing
# Test on specific distribution
./scripts/build-test-single.sh ubuntu-22-04
# Test across all Linux distributions
./scripts/run-all-tests.sh

🐳 Universal - DockerProvider (Cross-Platform) - ENHANCED

# Install Docker Desktop
winget install Docker.DockerDesktop
# Or download from: https://docker.com/products/docker-desktop
# Install Python dependencies
pip install docker cloudpickle

# Install Docker Desktop
brew install --cask docker
# Or download from: https://docker.com/products/docker-desktop
# Install Python dependencies
pip install docker cloudpickle

# Install Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Add user to docker group (avoid sudo)
sudo usermod -aG docker $USER
newgrp docker
# Install Python dependencies
pip install docker cloudpickle

from tinyagent import TinyCodeAgent
# 🌟 Zero Configuration (Recommended)
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="docker",
 working_directory="/path/to/your/project" # 🔄 Auto-mounted to /workspace
)
# ✨ Dynamic System Context: AI knows it's in container with correct info
# 🗂️ Unified File Operations: Same API as native providers
# 🔧 Automatic Volume Mounting: Based on working directory
# 🏗️ Pre-configured Templates
from tinyagent.code_agent.providers.docker_provider import DockerProvider
# Data Science Optimized
ds_agent = DockerProvider.for_data_science(
 working_directory="/data/project",
 environment_variables={"JUPYTER_ENABLE_LAB": "yes"}
)
# Web Development Optimized 
web_agent = DockerProvider.for_web_development(
 working_directory="/web/project",
 environment_variables={"NODE_ENV": "development"}
)

from tinyagent.code_agent.providers.docker_image_builder import DockerImageBuilder
# Custom Image Builder
builder = DockerImageBuilder("python:3.11-slim")
builder.add_system_packages("git", "curl", "nodejs")
builder.add_python_packages("fastapi", "pandas", "matplotlib")
builder.set_environment(API_URL="http://localhost:8000")
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="docker",
 provider_config={
 "dockerfile_content": builder.generate_dockerfile(),
 "docker_image": builder.get_image_tag(),
 "build_image": True,
 "working_directory": "/my/project",
 "enable_network": True,
 "memory_limit": "2g",
 "cpu_limit": "2.0"
 }
)
# 📝 Inline Dockerfile
custom_dockerfile = """
FROM python:3.11-slim
RUN apt-get update && apt-get install -y git nodejs npm
RUN pip install fastapi uvicorn pandas
ENV NODE_ENV=development
USER 1000:1000
WORKDIR /workspace
"""
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="docker",
 provider_config={
 "dockerfile_content": custom_dockerfile,
 "build_image": True
 }
)

# Verify Docker installation
docker --version
docker info
# Test enhanced provider
python -c "
from tinyagent.code_agent.providers.docker_provider import DockerProvider
print('✅ DockerProvider available:', DockerProvider.is_supported())
"
# Test with actual execution (requires Docker)
python -c "
import asyncio
from tinyagent import TinyCodeAgent

async def test():
 agent = TinyCodeAgent(provider='docker', working_directory='.')
 result = await agent.execute_python(['print(\"🐳 Docker container working!\")'])
 print(result.get('printed_output', ''))

asyncio.run(test())
"

☁️ Cloud - ModalProvider (Production)

# Install Modal
pip install modal
# Authenticate
modal token new

from tinyagent import TinyCodeAgent
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="modal",
 provider_config={
 "pip_packages": ["requests", "pandas", "matplotlib", "seaborn"],
 "timeout": 300,
 "cpu_count": 2,
 "memory_mb": 2048
 },
 local_execution=False # Uses Modal cloud
)

🔧 Advanced Provider Configuration

Environment Variables

# Set environment variables for all providers
common_env = {
 "PROJECT_ROOT": "/workspace",
 "API_KEY": "your-secret-key",
 "GITHUB_TOKEN": "ghp_xxxx", # For git operations
 "CUSTOM_CONFIG": "production"
}
agent = TinyCodeAgent(
 provider="auto", # Auto-select best provider
 provider_config={
 "environment_variables": common_env,
 "additional_read_dirs": ["/data"],
 "additional_write_dirs": ["/output"]
 }
)

Git Operations Support

# Configure git operations across all providers
git_config = {
 "environment_variables": {
 "GIT_AUTHOR_NAME": "TinyAgent",
 "GIT_AUTHOR_EMAIL": "agent@example.com",
 "GITHUB_USERNAME": "your-username",
 "GITHUB_TOKEN": "your-token"
 }
}
agent = TinyCodeAgent(
 provider="auto",
 provider_config=git_config
)
# Git operations work across all providers
result = await agent.execute_shell(["git", "clone", "https://github.com/user/repo.git"])

Security Best Practices

1. Principle of Least Privilege

# Only grant necessary directory access
secure_config = {
 "additional_read_dirs": ["/app/data"], # Only data directory
 "additional_write_dirs": ["/app/output"], # Only output directory
 "bypass_shell_safety": False, # Enable command filtering
 "enable_network": False # Disable network access
}

2. Environment Isolation

# Clean environment with only necessary variables
clean_env = {
 "PATH": "/usr/local/bin:/usr/bin:/bin",
 "PYTHONPATH": "/app",
 "PROJECT_ENV": "sandbox"
 # Don't include sensitive host environment
}

3. Resource Limits

# Prevent resource exhaustion
resource_limits = {
 "memory_limit": "512m", # Limit memory usage
 "cpu_limit": "1.0", # Limit CPU usage
 "timeout": 180, # 3 minute timeout
 "max_processes": 10 # Process limit (Docker)
}

🧪 Testing Your Sandbox Setup

Automated Testing

import asyncio
from tinyagent import TinyCodeAgent
async def test_sandbox():
 """Test sandbox functionality across providers."""
 
 providers = ["auto", "seatbelt", "bubblewrap", "docker", "modal"]
 
 for provider in providers:
 try:
 agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider=provider,
 provider_fallback=True # Allow fallback
 )
 
 # Test Python execution
 result = await agent.execute_python([
 "import platform",
 "print(f'Running on: {platform.system()}')",
 "print('Sandbox test successful!')"
 ])
 
 print(f"✅ {provider}: {result['printed_output'].strip()}")
 
 except Exception as e:
 print(f"❌ {provider}: {str(e)}")
 
 finally:
 if 'agent' in locals():
 await agent.cleanup()
# Run the test
asyncio.run(test_sandbox())

Manual Testing

# Test filesystem isolation
result = await agent.execute_python([
 "import os",
 "print('Current directory:', os.getcwd())",
 "print('Can access /etc/passwd:', os.path.exists('/etc/passwd'))",
 "print('Can write to /tmp:', os.access('/tmp', os.W_OK))"
])
# Test network isolation (should fail if disabled)
result = await agent.execute_python([
 "import requests",
 "response = requests.get('https://httpbin.org/ip', timeout=5)",
 "print('Network access:', response.status_code)"
])
# Test shell command filtering
result = await agent.execute_shell(["rm", "-rf", "/"]) # Should be blocked
result = await agent.execute_shell(["ls", "-la"]) # Should work

TinyCodeAgent - Advanced Code Execution with File Tools

Key New Features

Quick Start with Enhanced TinyCodeAgent

import asyncio
from tinyagent import TinyCodeAgent
async def main():
 # Zero-configuration setup (recommended)
 agent = TinyCodeAgent(
 model="gpt-4o-mini",
 api_key="your-openai-api-key",
 local_execution=True, # Auto-selects best provider for your platform
 
 # Enable all new tools
 enable_file_tools=True, # read_file, write_file, update_file, glob, grep
 enable_shell_tool=True, # Enhanced bash tool
 enable_todo_write=True, # Task management
 
 # Auto git checkpoints
 auto_git_checkpoint=True,
 
 # Rich terminal UI
 ui="rich"
 )
 
 try:
 # Complex cross-platform task with file operations
 result = await agent.run("""
 I need to analyze and refactor a Python project:

 1. Use glob to find all Python files in the project
 2. Use grep to identify functions that need refactoring
 3. Read key files to understand the architecture 
 4. Create a refactoring plan with todos
 5. Implement improvements with file operations
 6. Run tests to verify changes

 Use the todo system to track progress throughout.
 This will work on macOS (seatbelt), Linux (bubblewrap), or Windows (docker)!
 """)
 
 print(result)
 finally:
 await agent.close()
asyncio.run(main())

Platform-Specific Examples

macOS Development Setup

# Optimized for macOS development with Seatbelt sandbox
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="seatbelt",
 provider_config={
 "additional_read_dirs": ["/Users/username/projects"],
 "additional_write_dirs": ["/Users/username/projects/output"],
 "environment_variables": {
 "GITHUB_TOKEN": "your-token",
 "PROJECT_ROOT": "/Users/username/projects"
 },
 "bypass_shell_safety": True # Enable shell commands for development
 },
 local_execution=True,
 enable_file_tools=True,
 ui="rich"
)

Linux Server Setup

# Optimized for Linux servers with Bubblewrap isolation
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="bubblewrap",
 provider_config={
 "additional_read_dirs": ["/home/user/projects"],
 "additional_write_dirs": ["/home/user/output"],
 "environment_variables": {
 "GITHUB_USERNAME": "username",
 "GITHUB_TOKEN": "token"
 },
 "bypass_shell_safety": False # Security-first for servers
 },
 local_execution=True,
 enable_file_tools=True
)

Windows/Universal Setup

# Universal setup using Docker (works on Windows, macOS, Linux)
agent = TinyCodeAgent(
 model="gpt-4o-mini",
 provider="docker",
 provider_config={
 "memory_limit": "1g",
 "cpu_limit": "2.0",
 "enable_network": True, # Enable for git operations
 "environment_variables": {
 "GITHUB_TOKEN": "your-token",
 "PROJECT_ROOT": "/workspace"
 },
 "additional_read_dirs": ["/host/data"],
 "additional_write_dirs": ["/host/output"]
 },
 enable_file_tools=True,
 ui="rich"
)

TinyCodeAgent with Gradio UI

from tinyagent.code_agent.example import run_example
import asyncio
# Run the full example with Gradio interface
asyncio.run(run_example())

Key Features

Cross-Platform Provider System

# Automatic provider selection (recommended)
agent = TinyCodeAgent(local_execution=True) 
# Auto-selects: macOS→Seatbelt, Linux→Bubblewrap, Windows→Docker
# Explicit provider selection
agent = TinyCodeAgent(provider="seatbelt") # macOS native sandbox
agent = TinyCodeAgent(provider="bubblewrap") # Linux native sandbox
agent = TinyCodeAgent(provider="docker") # Universal container-based
agent = TinyCodeAgent(provider="modal") # Cloud execution
# Provider with fallback
agent = TinyCodeAgent(
 provider="bubblewrap", # Try Linux native first
 provider_fallback=True, # Fall back to docker if unavailable
 local_execution=True
)
# Check available providers
from tinyagent import TinyCodeAgent
available = TinyCodeAgent.get_available_providers()
print(f"Available: {available}") # ['seatbelt', 'docker', 'modal']
best_local = TinyCodeAgent.get_best_local_provider()
print(f"Best local: {best_local}") # 'seatbelt' on macOS, 'bubblewrap' on Linux

Example Use Cases

result = await agent.run("""
What are trending spaces on huggingface today?
""")
# Agent will create a python tool to request HuggingFace API and find trending spaces

response = await agent.run(dedent("""
Suggest me 13 tags for my Etsy Listing, each tag should be multiworded and maximum 20 characters. Each word should be used only once in the whole corpus, And tags should cover different ways people are searching for the product on Etsy.
- You should use your coding abilities to check your answer pass the criteria and continue your job until you get to the answer.

My Product is **Wedding Invitation Set of 3, in sage green color, with a gold foil border.**
"""),max_turns=20)
print(response)
# LLM is not good at this task, counting characters, avoid duplicates, but with the power of code, tiny model like gpt-5-mini can do it without any problem.

Full Configuration Options

from tinyagent import TinyCodeAgent
from tinyagent.code_agent.tools.file_tools import ProductionApprovalHook
# Complete cross-platform configuration example
agent = TinyCodeAgent(
 # Core configuration
 model="gpt-4o-mini",
 api_key="your-api-key",
 
 # Cross-platform provider selection
 provider="auto", # Auto-select best provider
 provider_fallback=True, # Enable fallback chain
 local_execution=True, # Prefer local over cloud
 
 # Universal provider configuration
 provider_config={
 # Common options (work across all providers)
 "additional_read_dirs": ["/path/to/data", "/path/to/config"],
 "additional_write_dirs": ["/path/to/output"],
 "environment_variables": {
 "PROJECT_ROOT": "/workspace",
 "GITHUB_TOKEN": "your-token",
 "API_KEY": "your-api-key"
 },
 "bypass_shell_safety": True, # Enable shell commands
 
 # Platform-specific options (automatically filtered)
 "python_env_path": "/usr/local/bin/python3", # Seatbelt/Bubblewrap
 "memory_limit": "1g", # Docker/Modal
 "cpu_limit": "2.0", # Docker/Modal
 "timeout": 300, # All providers
 "pip_packages": ["requests", "pandas"], # Modal/Docker
 },
 
 # Tool enablement (all True by default)
 enable_python_tool=True, # Python code execution
 enable_shell_tool=True, # Enhanced bash tool
 enable_file_tools=True, # read_file, write_file, update_file, glob, grep
 enable_todo_write=True, # Task management system
 
 # Python environment setup
 authorized_imports=["requests", "pandas", "numpy", "matplotlib", "seaborn"],
 pip_packages=["requests", "pandas", "matplotlib"], # For cloud providers
 
 # File and shell operations
 default_workdir="/workspace",
 auto_git_checkpoint=True, # Auto git commits after shell commands
 
 # Output control
 truncation_config={
 "max_tokens": 5000,
 "max_lines": 300, 
 "enabled": True
 },
 
 # UI and logging
 ui="rich", # "rich", "jupyter", or None
 log_manager=None, # Optional LoggingManager instance
 
 # Security and validation
 check_string_obfuscation=True, # Check for potential obfuscated code
 
 # Memory management
 summary_config={
 "max_messages": 50,
 "summary_model": "gpt-4o-mini"
 }
)
# Add custom file operation controls
file_hook = ProductionApprovalHook() # Requires approval for file modifications
agent.add_callback(file_hook)

Provider-Specific Configuration

macOS - Seatbelt Provider Configuration

seatbelt_config = {
 "python_env_path": "/usr/local/bin/python3",
 "additional_read_dirs": ["/Users/username/projects"],
 "additional_write_dirs": ["/Users/username/output"],
 "environment_variables": {
 "GITHUB_TOKEN": "your-token",
 "PROJECT_ROOT": "/Users/username/projects"
 },
 "bypass_shell_safety": True # More permissive for local development
}
agent = TinyCodeAgent(
 provider="seatbelt", 
 provider_config=seatbelt_config,
 local_execution=True # Required for seatbelt
)

Linux - Bubblewrap Provider Configuration

bubblewrap_config = {
 "additional_read_dirs": ["/home/user/projects"],
 "additional_write_dirs": ["/home/user/output"],
 "environment_variables": {
 "GITHUB_USERNAME": "username",
 "GITHUB_TOKEN": "your-token",
 "PROJECT_ROOT": "/home/user/projects"
 },
 "bypass_shell_safety": False # More restrictive for servers
}
agent = TinyCodeAgent(
 provider="bubblewrap",
 provider_config=bubblewrap_config,
 local_execution=True # Required for bubblewrap
)

Universal - Docker Provider Configuration

docker_config = {
 "docker_image": "tinyagent-runtime:latest", # Auto-built if missing
 "memory_limit": "1g", # Resource limits
 "cpu_limit": "2.0",
 "timeout": 300, # 5 minute timeout
 "enable_network": True, # Enable for git operations
 "environment_variables": {
 "GITHUB_TOKEN": "your-token",
 "PROJECT_ROOT": "/workspace"
 },
 "additional_read_dirs": ["/host/data"],
 "additional_write_dirs": ["/host/output"]
}
agent = TinyCodeAgent(
 provider="docker",
 provider_config=docker_config
 # Works on Windows, macOS, and Linux
)

Cloud - Modal Provider Configuration

modal_config = {
 "pip_packages": ["requests", "pandas", "matplotlib"],
 "timeout": 300,
 "cpu_count": 2,
 "memory_mb": 2048,
 "bypass_shell_safety": False, # More restrictive for cloud
 "additional_safe_shell_commands": ["custom_cmd"]
}
agent = TinyCodeAgent(
 provider="modal", 
 provider_config=modal_config,
 local_execution=False # Use Modal cloud
)

Automatic Git Checkpoints

# Enable automatic Git checkpoints during initialization
agent = TinyCodeAgent(
 model="gpt-5-mini",
 auto_git_checkpoint=True # Enable automatic Git checkpoints
)
# Or enable/disable it later
agent.enable_auto_git_checkpoint(True) # Enable
agent.enable_auto_git_checkpoint(False) # Disable
# Check current status
is_enabled = agent.get_auto_git_checkpoint_status()

🛡️ Security Model Comparison

🎯 Provider Selection Guide

🚀 Subagent Tools - Parallel Task Execution (New!)

Quick Start with Subagents

import asyncio
from tinyagent import TinyAgent
from tinyagent.tools.subagent import create_general_subagent, create_coding_subagent
async def main():
 # Create main agent
 main_agent = TinyAgent(
 model="gpt-5-mini",
 api_key="your-api-key"
 )
 
 # Add a general-purpose subagent
 helper = create_general_subagent(
 name="helper",
 model="gpt-5-mini",
 max_turns=15,
 enable_python=True,
 enable_shell=True
 )
 main_agent.add_tool(helper)
 
 # Add a specialized coding subagent 
 coder = create_coding_subagent(
 name="coder",
 model="gpt-5-mini",
 max_turns=25
 )
 main_agent.add_tool(coder)
 
 # Check available tools (subagents appear as tools)
 available_tools = list(main_agent.custom_tool_handlers.keys())
 print(f"Available tools: {available_tools}") # ['TodoWrite', 'helper', 'coder']
 
 # Use subagents in parallel
 result = await main_agent.run("""
 I need help with a Python project:
 1. Use coder to implement a binary search algorithm
 2. Use helper to create unit tests for it
 3. Use helper to benchmark the performance

 Make sure both tasks run efficiently and provide comprehensive results.
 """)
 
 print(result)
asyncio.run(main())

Specialized Subagent Types

from tinyagent.tools.subagent import (
 create_research_subagent,
 create_coding_subagent, 
 create_analysis_subagent,
 create_writing_subagent,
 create_planning_subagent
)
# Research subagent - optimized for information gathering
researcher = create_research_subagent(
 name="researcher",
 model="gpt-5",
 max_turns=20
)
# Coding subagent - with Python/shell execution
coder = create_coding_subagent(
 name="coder", 
 model="claude-3-sonnet",
 local_execution=True,
 timeout=300 # 5 minute timeout
)
# Analysis subagent - for data analysis tasks
analyst = create_analysis_subagent(
 name="analyst",
 model="gpt-5-mini",
 enable_python_tool=True
)
# Writing subagent - for content creation
writer = create_writing_subagent(
 name="writer",
 model="claude-3-haiku",
 temperature=0.3
)
# Planning subagent - for strategy and planning
planner = create_planning_subagent(
 name="planner",
 model="gpt-5",
 max_turns=15
)
# Add all subagents to your main agent
for subagent in [researcher, coder, analyst, writer, planner]:
 main_agent.add_tool(subagent)

Advanced Configuration with Parent Inheritance

from tinyagent.tools.subagent import SubagentConfig, create_subagent_tool
# Create main agent with callbacks and configuration
main_agent = TinyAgent(
 model="gpt-5-mini",
 api_key="your-key",
 log_manager=my_log_manager,
 session_id="main-session"
)
# Create configuration that inherits from parent
config = SubagentConfig.from_parent_agent(
 parent_agent=main_agent, # Inherits API keys, logging, session info
 model="claude-3-sonnet", # Override specific parameters
 max_turns=20,
 enable_python_tool=True,
 timeout=300, # 5 minute timeout
 working_directory="/tmp/subagent"
)
# Create custom subagent with inherited configuration
specialized_tool = create_subagent_tool(
 name="specialist", 
 config=config,
 description="A specialized agent for complex analysis tasks"
)
main_agent.add_tool(specialized_tool)

Custom Agent Factories

from tinyagent.tools.subagent import SubagentConfig, create_subagent_tool
from tinyagent import TinyCodeAgent
def my_custom_factory(**kwargs):
 """Custom factory for creating specialized agents."""
 return TinyCodeAgent(
 provider="modal", # Use Modal.com for execution
 provider_config={
 "image": "python:3.11-slim",
 "timeout": 180,
 "cpu_count": 2
 },
 tools=[custom_tool_1, custom_tool_2], # Add custom tools
 **kwargs
 )
# Create subagent with custom factory
config = SubagentConfig(
 model="gpt-5-mini",
 max_turns=15,
 timeout=600
)
custom_subagent = create_subagent_tool(
 name="custom_executor",
 config=config,
 agent_factory=my_custom_factory,
 description="Custom subagent with Modal.com execution"
)
main_agent.add_tool(custom_subagent)

Key Benefits of Subagents

Subagent vs Regular Tools

How the TinyAgent Hook System Works

How Hooks Work

Example: Adding a Custom Hook

def my_logger_hook(event_name, agent, **kwargs):
 print(f"[{event_name}] {kwargs}")
agent.add_callback(my_logger_hook)

Example: Async Hook

async def my_async_hook(event_name, agent, **kwargs):
 if event_name == "agent_end":
 print("Agent finished with result:", kwargs.get("result"))
agent.add_callback(my_async_hook)

Example: Class-based Hook

class MyHook:
 async def __call__(self, event_name, agent, **kwargs):
 if event_name == "llm_start":
 print("LLM is starting...")
agent.add_callback(MyHook())

How to Extend the Hook System

🚨 Important: Hook Interface Guidelines

New Hook Interface (Recommended)

class MyHook:
 async def __call__(self, event_name: str, agent, *args, **kwargs):
 """
 Hook that works with both new and legacy interfaces.

 Args:
 event_name: The event name
 agent: The TinyAgent instance
 *args: May contain kwargs_dict for new interface
 **kwargs: Legacy interface or fallback
 """
 # Handle both interfaces for maximum compatibility
 if args and isinstance(args[0], dict):
 # New interface: kwargs_dict passed as positional argument
 event_kwargs = args[0]
 else:
 # Legacy interface: use **kwargs
 event_kwargs = kwargs
 
 if event_name == "llm_start":
 # ✅ Modify event_kwargs["messages"] (what goes to LLM)
 messages = event_kwargs.get("messages", [])
 
 # Example: Add cache control, clean up fields, etc.
 for message in messages:
 if isinstance(message, dict) and "created_at" in message:
 del message["created_at"] # Remove unsupported fields

Legacy Hook Interface (Still Supported)

async def my_legacy_hook(event_name, agent, **kwargs):
 if event_name == "llm_start":
 # ⚠️ LIMITATION: Cannot modify messages sent to LLM
 # This interface is read-only for message modification
 messages = kwargs.get("messages", [])
 print(f"LLM will be called with {len(messages)} messages")

❌ DON'T: Modify Conversation History

async def bad_hook(event_name, agent, *args, **kwargs):
 if event_name == "llm_start":
 # ❌ WRONG: Don't modify agent.messages (conversation history)
 agent.messages = modified_messages # This corrupts conversation history!

🏗️ Architecture Explanation

📝 Use Cases for Message Modification

🔧 Built-in Hooks Using New Interface

🚀 Anthropic Prompt Caching (New!)

Quick Start

from tinyagent import TinyAgent
from tinyagent.hooks import anthropic_prompt_cache
agent = TinyAgent(model="claude-3-5-sonnet-20241022")
# Add Anthropic prompt caching
cache_callback = anthropic_prompt_cache()
agent.add_callback(cache_callback)
# Use normally - caching happens automatically for large messages
response = await agent.run("Long prompt here...")

How It Works

Supported Models

Benefits

List of Available Hooks & Tools

Core Hooks

File Tools 🗂️

Task Management 📋

Subagent Tools 🚀

Using the GradioCallback Hook

import asyncio
from tinyagent import TinyAgent
from tinyagent.hooks.gradio_callback import GradioCallback
async def main():
 # 1. Initialize your agent
 agent = TinyAgent(model="gpt-5-mini", api_key="YOUR_API_KEY")
 # 2. (Optional) Add tools or connect to MCP servers
 # await agent.connect_to_server("npx", ["-y","@openbnb/mcp-server-airbnb","--ignore-robots-txt"])
 # 3. Instantiate the Gradio UI callback
 gradio_ui = GradioCallback(
 file_upload_folder="uploads/",
 show_thinking=True,
 show_tool_calls=True
 )
 # 4. Register the callback with the agent
 agent.add_callback(gradio_ui)
 # 5. Launch the web interface (non-blocking)
 gradio_ui.launch(
 agent,
 title="TinyAgent Chat",
 description="Ask me to plan a trip or fetch data!",
 share=False,
 prevent_thread_lock=True
 )
if __name__ == "__main__":
 asyncio.run(main())

Build your own TinyAgent

Contributing Hooks

License