suna/README.md

# AgentPress: Building Blocks for AI Agents

AgentPress is not a agent framework - it's a collection of lightweight, modular utilities that serve as building blocks for creating AI agents. Think of it as "shadcn/ui for AI agents" - a set of utils to copy, paste, and customize in order to quickly bootstrap your AI App / Agent.

AgentPress provides Messages[] API on Steroids called "Threads", a ThreadManager with automatic Tool Execution and a simple StateManager.

## Installation & Setup

1. Install the package:
```bash
pip install agentpress
```

2. Initialize AgentPress in your project:
```bash
agentpress init
```
This will create a `agentpress` directory with the core utilities you can customize.

## Key Components

- **Threads**: Simple message thread handling utilities
- **Automatic Tool**: Flexible tool definition and automatic execution
- **State Management**: Basic JSON-based state persistence
- **LLM Integration**: Provider-agnostic LLM calls via LiteLLM

## Quick Start

1. Set up your environment variables (API keys, etc.) in a `.env` file.

2. Create a tool - copy this code directly into your project:
```python
from agentpress.tool import Tool, ToolResult, tool_schema

class CalculatorTool(Tool):
    @tool_schema({
        "name": "add",
        "description": "Add two numbers",
        "parameters": {
            "type": "object",
            "properties": {
                "a": {"type": "number"},
                "b": {"type": "number"}
            },
            "required": ["a", "b"]
        }
    })
    async def add(self, a: float, b: float) -> ToolResult:
        return self.success_response(f"The sum is {a + b}")
```

3. Use the Thread Manager - customize as needed:
```python
import asyncio
from agentpress.thread_manager import ThreadManager

async def main():
    manager = ThreadManager()
    manager.add_tool(CalculatorTool)
    thread_id = await manager.create_thread()
    
    # Add your custom logic here
    await manager.add_message(thread_id, {
        "role": "user", 
        "content": "What's 2 + 2?"
    })
    
    response = await manager.run_thread(
        thread_id=thread_id,
        system_message={
            "role": "system", 
            "content": "You are a helpful assistant with calculation abilities."
        },
        model_name="gpt-4",
        use_tools=True,
        execute_model_tool_calls=True
    )
    print("Response:", response)

asyncio.run(main())
```

## Building Your Own Agent

Example of a customized autonomous agent:
```python
import asyncio
from agentpress.thread_manager import ThreadManager
from your_custom_tools import CustomTool

async def run_agent(max_iterations=5):
    # Create your own manager instance
    manager = ThreadManager()
    thread_id = await manager.create_thread()
    
    # Add your custom tools
    manager.add_tool(CustomTool)
    
    # Define your agent's behavior
    system_message = {
        "role": "system",
        "content": "Your custom system message here"
    }
    
    # Implement your control loop
    for iteration in range(max_iterations):
        response = await manager.run_thread(
            thread_id=thread_id,
            system_message=system_message,
            model_name="your-preferred-model",
            # Customize parameters as needed
        )
        
        # Add your custom logic here
        process_response(response)

if __name__ == "__main__":
    asyncio.run(run_agent())
```

## Development

1. Clone for reference:
```bash
git clone https://github.com/kortix-ai/agentpress
cd agentpress
```

2. Install dependencies:
```bash
pip install poetry
poetry install
```

## Philosophy

- **Modular**: Pick and choose what you need. Each component is designed to work independently.
- **Agnostic**: Built on LiteLLM, supporting any LLM provider. Minimal opinions, maximum flexibility.
- **Simplicity**: Clean, readable code that's easy to understand and modify.
- **Plug & Play**: Start with our defaults, then customize to your needs.
- **No Lock-in**: Take full ownership of the code. Copy what you need directly into your codebase.

## What Makes AgentPress Different?

Unlike monolithic frameworks that dictate how you should build your AI agents, AgentPress provides the essential building blocks while letting you maintain complete control over your implementation. It's designed for developers who want to:

- Quickly prototype AI agents without committing to a heavy framework
- Maintain full ownership and understanding of their agent's code
- Customize and extend functionality based on specific needs
- Learn best practices for building AI agents through clear, practical examples

## Contributing

We welcome contributions! Feel free to:
- Submit issues for bugs or suggestions
- Fork the repository and send pull requests
- Share how you've used AgentPress in your projects

## License

[MIT License](LICENSE)

Built with ❤️ by [Kortix AI Corp](https://kortix.ai)