# AgentPress: Building Blocks for AI Agents
AgentPress is a collection of _simple, but powerful_ utilities that serve as building blocks for creating AI agents. *Plug, play, and customize.*
See [How It Works](#how-it-works) for an explanation of this flow.
## Core Components
- **Threads**: Manage Messages[] as threads.
- **Tools**: Register code as callable tools with definitions in both OpenAPI and XML
- **Response Processing**: Support for native-LLM OpenAPI and XML-based tool calling
- **State Management**: Thread-safe JSON key-value state management
- **LLM**: +100 LLMs using the OpenAI I/O Format powered by LiteLLM
## Installation & Setup
1. Install the package:
```bash
pip install agentpress
```
2. Initialize AgentPress in your project:
```bash
agentpress init
```
Creates a `agentpress` directory with all the core utilities.
Check out [File Overview](#file-overview) for explanations of the generated files.
3. If you selected the example agent during initialization:
- Creates an `agent.py` file with a web development agent example
- Creates a `tools` directory with example tools:
- `files_tool.py`: File operations (create/update files, read directory and load into state)
- `terminal_tool.py`: Terminal command execution
- Creates a `workspace` directory for the agent to work in
## Quick Start
1. Set up your environment variables in a `.env` file:
```bash
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
GROQ_API_KEY=your_key_here
```
2. Create a calculator tool with OpenAPI schema:
```python
from agentpress.tool import Tool, ToolResult, openapi_schema
class CalculatorTool(Tool):
@openapi_schema({
"type": "function",
"function": {
"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:
try:
result = a + b
return self.success_response(f"The sum is {result}")
except Exception as e:
return self.fail_response(f"Failed to add numbers: {str(e)}")
```
3. Or create a tool with XML schema:
```python
from agentpress.tool import Tool, ToolResult, xml_schema
class FilesTool(Tool):
@xml_schema(
tag_name="create-file",
mappings=[
{"param_name": "file_path", "node_type": "attribute", "path": "."},
{"param_name": "file_contents", "node_type": "content", "path": "."}
],
example='''
<create-file file_path="path/to/file">
File contents go here
</create-file>
'''
)
async def create_file(self, file_path: str, file_contents: str) -> ToolResult:
# Implementation here
pass
```
4. Use the Thread Manager with tool execution:
```python
import asyncio
from agentpress.thread_manager import ThreadManager
from calculator_tool import CalculatorTool
async def main():
# Initialize thread manager and add tools
manager = ThreadManager()
manager.add_tool(CalculatorTool)
# Create a new thread
thread_id = await manager.create_thread()
# Add your message
await manager.add_message(thread_id, {
"role": "user",
"content": "What's 2 + 2?"
})
# Run with streaming and tool execution
response = await manager.run_thread(
thread_id=thread_id,
system_message={
"role": "system",
"content": "You are a helpful assistant with calculation abilities."
},
model_name="anthropic/claude-3-5-sonnet-latest",
execute_tools=True,
native_tool_calling=True, # Contrary to xml_tool_calling = True
parallel_tool_execution=True # Will execute tools in parallel, contrary to sequential (one after another)
)
asyncio.run(main())
```
5. View conversation threads in a web UI:
```bash
streamlit run agentpress/thread_viewer_ui.py
```
## How It Works
Each AI agent iteration follows a clear, modular flow:
1. **Message & LLM Handling**
- Messages are managed in threads via `ThreadManager`
- LLM API calls are made through a unified interface (`llm.py`)
- Supports streaming responses for real-time interaction
2. **Response Processing**
- LLM returns both content and tool calls
- Content is streamed in real-time
- Tool calls are parsed using either:
- Standard OpenAPI function calling
- XML-based tool definitions
- Custom parsers (extend `ToolParserBase`)
3. **Tool Execution**
- Tools are executed either:
- In real-time during streaming (`execute_tools_on_stream`)
- After complete response
- In parallel or sequential order
- Supports both standard and XML tool formats
- Extensible through `ToolExecutorBase`
4. **Results Management**
- Results from both content and tool executions are handled
- Supports different result formats (standard/XML)
- Customizable through `ResultsAdderBase`
This modular architecture allows you to:
- Use standard OpenAPI function calling
- Switch to XML-based tool definitions
- Create custom processors by extending base classes
- Mix and match different approaches
## File Overview
### Core Components
#### agentpress/llm.py
LLM API interface using LiteLLM. Supports 100+ LLMs with OpenAI-compatible format. Includes streaming, retry logic, and error handling.
#### agentpress/thread_manager.py
Manages conversation threads with support for:
- Message history management
- Tool registration and execution
- Streaming responses
- Both OpenAPI and XML tool calling patterns
#### agentpress/tool.py
Base infrastructure for tools with:
- OpenAPI schema decorator for standard function calling
- XML schema decorator for XML-based tool calls
- Standardized ToolResult responses
#### agentpress/tool_registry.py
Central registry for tool management:
- Registers both OpenAPI and XML tools
- Maintains tool schemas and implementations
- Provides tool lookup and validation
#### agentpress/state_manager.py
Thread-safe state persistence:
- JSON-based key-value storage
- Atomic operations with locking
- Automatic file handling
### Response Processing
#### agentpress/llm_response_processor.py
Handles LLM response processing with support for:
- Streaming and complete responses
- Tool call extraction and execution
- Result formatting and message management
#### Standard Processing
- `standard_tool_parser.py`: Parses OpenAPI function calls
- `standard_tool_executor.py`: Executes standard tool calls
- `standard_results_adder.py`: Manages standard results
#### XML Processing
- `xml_tool_parser.py`: Parses XML-formatted tool calls
- `xml_tool_executor.py`: Executes XML tool calls
- `xml_results_adder.py`: Manages XML results
## Philosophy
- **Plug & Play**: Start with our defaults, then customize to your needs.
- **Agnostic**: Built on LiteLLM, supporting any LLM provider. Minimal opinions, maximum flexibility.
- **Simplicity**: Clean, readable code that's easy to understand and modify.
- **No Lock-in**: Take full ownership of the code. Copy what you need directly into your codebase.
## 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
## Development
1. Clone:
```bash
git clone https://github.com/kortix-ai/agentpress
cd agentpress
```
2. Install dependencies:
```bash
pip install poetry
poetry install
```
3. For quick testing:
```bash
pip install -e .
```
## License
[MIT License](LICENSE)
Built with ❤️ by [Kortix AI Corp](https://kortix.ai)
Raw data
{
"_id": null,
"home_page": "https://github.com/kortix-ai/agentpress",
"name": "agentpress",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "llm, ai, agents, ai agents, ai agent framework",
"author": "marko-kraemer",
"author_email": "mail@markokraemer.com",
"download_url": "https://files.pythonhosted.org/packages/43/0d/09f111eb0b858d1dfd6965335a10e4a8c40714620889da5d3336df33c0ac/agentpress-0.1.12.tar.gz",
"platform": null,
"description": "# AgentPress: Building Blocks for AI Agents\n\nAgentPress is a collection of _simple, but powerful_ utilities that serve as building blocks for creating AI agents. *Plug, play, and customize.*\n\n\n\nSee [How It Works](#how-it-works) for an explanation of this flow.\n\n## Core Components\n- **Threads**: Manage Messages[] as threads.\n- **Tools**: Register code as callable tools with definitions in both OpenAPI and XML\n- **Response Processing**: Support for native-LLM OpenAPI and XML-based tool calling\n- **State Management**: Thread-safe JSON key-value state management\n- **LLM**: +100 LLMs using the OpenAI I/O Format powered by LiteLLM\n\n## Installation & Setup\n\n1. Install the package:\n```bash\npip install agentpress\n```\n\n2. Initialize AgentPress in your project:\n```bash\nagentpress init\n```\nCreates a `agentpress` directory with all the core utilities.\nCheck out [File Overview](#file-overview) for explanations of the generated files.\n\n3. If you selected the example agent during initialization:\n - Creates an `agent.py` file with a web development agent example\n - Creates a `tools` directory with example tools:\n - `files_tool.py`: File operations (create/update files, read directory and load into state)\n - `terminal_tool.py`: Terminal command execution\n - Creates a `workspace` directory for the agent to work in\n\n\n\n\n## Quick Start\n\n1. Set up your environment variables in a `.env` file:\n```bash\nOPENAI_API_KEY=your_key_here\nANTHROPIC_API_KEY=your_key_here\nGROQ_API_KEY=your_key_here\n```\n\n2. Create a calculator tool with OpenAPI schema:\n```python\nfrom agentpress.tool import Tool, ToolResult, openapi_schema\n\nclass CalculatorTool(Tool):\n @openapi_schema({\n \"type\": \"function\",\n \"function\": {\n \"name\": \"add\",\n \"description\": \"Add two numbers\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"a\": {\"type\": \"number\"},\n \"b\": {\"type\": \"number\"}\n },\n \"required\": [\"a\", \"b\"]\n }\n }\n })\n async def add(self, a: float, b: float) -> ToolResult:\n try:\n result = a + b\n return self.success_response(f\"The sum is {result}\")\n except Exception as e:\n return self.fail_response(f\"Failed to add numbers: {str(e)}\")\n```\n\n3. Or create a tool with XML schema:\n```python\nfrom agentpress.tool import Tool, ToolResult, xml_schema\n\nclass FilesTool(Tool):\n @xml_schema(\n tag_name=\"create-file\",\n mappings=[\n {\"param_name\": \"file_path\", \"node_type\": \"attribute\", \"path\": \".\"},\n {\"param_name\": \"file_contents\", \"node_type\": \"content\", \"path\": \".\"}\n ],\n example='''\n <create-file file_path=\"path/to/file\">\n File contents go here\n </create-file>\n '''\n )\n async def create_file(self, file_path: str, file_contents: str) -> ToolResult:\n # Implementation here\n pass\n```\n\n4. Use the Thread Manager with tool execution:\n```python\nimport asyncio\nfrom agentpress.thread_manager import ThreadManager\nfrom calculator_tool import CalculatorTool\n\nasync def main():\n # Initialize thread manager and add tools\n manager = ThreadManager()\n manager.add_tool(CalculatorTool)\n\n # Create a new thread\n thread_id = await manager.create_thread()\n \n # Add your message\n await manager.add_message(thread_id, {\n \"role\": \"user\", \n \"content\": \"What's 2 + 2?\"\n })\n \n # Run with streaming and tool execution\n response = await manager.run_thread(\n thread_id=thread_id,\n system_message={\n \"role\": \"system\", \n \"content\": \"You are a helpful assistant with calculation abilities.\"\n },\n model_name=\"anthropic/claude-3-5-sonnet-latest\",\n execute_tools=True,\n native_tool_calling=True, # Contrary to xml_tool_calling = True\n parallel_tool_execution=True # Will execute tools in parallel, contrary to sequential (one after another)\n )\n\nasyncio.run(main())\n```\n\n5. View conversation threads in a web UI:\n```bash\nstreamlit run agentpress/thread_viewer_ui.py\n```\n\n## How It Works\n\nEach AI agent iteration follows a clear, modular flow:\n\n1. **Message & LLM Handling**\n - Messages are managed in threads via `ThreadManager`\n - LLM API calls are made through a unified interface (`llm.py`)\n - Supports streaming responses for real-time interaction\n\n2. **Response Processing**\n - LLM returns both content and tool calls\n - Content is streamed in real-time\n - Tool calls are parsed using either:\n - Standard OpenAPI function calling\n - XML-based tool definitions\n - Custom parsers (extend `ToolParserBase`)\n\n3. **Tool Execution**\n - Tools are executed either:\n - In real-time during streaming (`execute_tools_on_stream`)\n - After complete response\n - In parallel or sequential order\n - Supports both standard and XML tool formats\n - Extensible through `ToolExecutorBase`\n\n4. **Results Management**\n - Results from both content and tool executions are handled\n - Supports different result formats (standard/XML)\n - Customizable through `ResultsAdderBase`\n\nThis modular architecture allows you to:\n- Use standard OpenAPI function calling\n- Switch to XML-based tool definitions\n- Create custom processors by extending base classes\n- Mix and match different approaches\n\n## File Overview\n\n### Core Components\n\n#### agentpress/llm.py\nLLM API interface using LiteLLM. Supports 100+ LLMs with OpenAI-compatible format. Includes streaming, retry logic, and error handling.\n\n#### agentpress/thread_manager.py\nManages conversation threads with support for:\n- Message history management\n- Tool registration and execution\n- Streaming responses\n- Both OpenAPI and XML tool calling patterns\n\n#### agentpress/tool.py\nBase infrastructure for tools with:\n- OpenAPI schema decorator for standard function calling\n- XML schema decorator for XML-based tool calls\n- Standardized ToolResult responses\n\n#### agentpress/tool_registry.py\nCentral registry for tool management:\n- Registers both OpenAPI and XML tools\n- Maintains tool schemas and implementations\n- Provides tool lookup and validation\n\n#### agentpress/state_manager.py\nThread-safe state persistence:\n- JSON-based key-value storage\n- Atomic operations with locking\n- Automatic file handling\n\n### Response Processing\n\n#### agentpress/llm_response_processor.py\nHandles LLM response processing with support for:\n- Streaming and complete responses\n- Tool call extraction and execution\n- Result formatting and message management\n\n#### Standard Processing\n- `standard_tool_parser.py`: Parses OpenAPI function calls\n- `standard_tool_executor.py`: Executes standard tool calls\n- `standard_results_adder.py`: Manages standard results\n\n#### XML Processing\n- `xml_tool_parser.py`: Parses XML-formatted tool calls\n- `xml_tool_executor.py`: Executes XML tool calls\n- `xml_results_adder.py`: Manages XML results\n\n## Philosophy\n- **Plug & Play**: Start with our defaults, then customize to your needs.\n- **Agnostic**: Built on LiteLLM, supporting any LLM provider. Minimal opinions, maximum flexibility.\n- **Simplicity**: Clean, readable code that's easy to understand and modify.\n- **No Lock-in**: Take full ownership of the code. Copy what you need directly into your codebase.\n\n## Contributing\n\nWe welcome contributions! Feel free to:\n- Submit issues for bugs or suggestions\n- Fork the repository and send pull requests\n- Share how you've used AgentPress in your projects\n\n## Development\n\n1. Clone:\n```bash\ngit clone https://github.com/kortix-ai/agentpress\ncd agentpress\n```\n\n2. Install dependencies:\n```bash\npip install poetry\npoetry install\n```\n\n3. For quick testing:\n```bash\npip install -e .\n```\n\n## License\n\n[MIT License](LICENSE)\n\nBuilt with \u2764\ufe0f by [Kortix AI Corp](https://kortix.ai)",
"bugtrack_url": null,
"license": "MIT",
"summary": "Building blocks for AI Agents",
"version": "0.1.12",
"project_urls": {
"Homepage": "https://github.com/kortix-ai/agentpress",
"Repository": "https://github.com/kortix-ai/agentpress"
},
"split_keywords": [
"llm",
" ai",
" agents",
" ai agents",
" ai agent framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f5d719c7d6b74cdb658e2eec45999682a157692a89df61751a444b7548ac8b10",
"md5": "6db497608e31780d5abda16a17ec5e65",
"sha256": "e595ab471a62bb609d16d4e56288ae61ff795dc7abfe19fe550e198a20109c95"
},
"downloads": -1,
"filename": "agentpress-0.1.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6db497608e31780d5abda16a17ec5e65",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 48621,
"upload_time": "2024-11-23T06:04:30",
"upload_time_iso_8601": "2024-11-23T06:04:30.306845Z",
"url": "https://files.pythonhosted.org/packages/f5/d7/19c7d6b74cdb658e2eec45999682a157692a89df61751a444b7548ac8b10/agentpress-0.1.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "430d09f111eb0b858d1dfd6965335a10e4a8c40714620889da5d3336df33c0ac",
"md5": "92a6e3b1ae868f4ca08df78f6e9998c5",
"sha256": "f69f587753e95dc2c93c4721bb349bc9df94d2f746c4951198f0d6e40c6c6a19"
},
"downloads": -1,
"filename": "agentpress-0.1.12.tar.gz",
"has_sig": false,
"md5_digest": "92a6e3b1ae868f4ca08df78f6e9998c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 38807,
"upload_time": "2024-11-23T06:04:31",
"upload_time_iso_8601": "2024-11-23T06:04:31.844522Z",
"url": "https://files.pythonhosted.org/packages/43/0d/09f111eb0b858d1dfd6965335a10e4a8c40714620889da5d3336df33c0ac/agentpress-0.1.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 06:04:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kortix-ai",
"github_project": "agentpress",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "agentpress"
}
JSON
