# apexagents

`apexagents` is a modular, lightweight, and production-ready Agentic AI framework inspired by minimal agent architectures. It helps developers build LLM-powered agents that can utilize tools, retain conversation memory, and cleanly integrate with external resources like MCP servers.

## Features

- **LLM Agnostic**: Powered by `litellm`, supporting 100+ LLM providers.
- **Tool Calling**: A clean `@tool` decorator to turn any Python function into an agent capability.
- **Memory Management**: Pluggable memory backends (In-Memory, SQLite) with intelligent summarization.
- **MCP Native**: First-class support for the Model Context Protocol (MCP) to connect with external tool servers.
- **Asynchronous**: Built with async support for modern streaming and non-blocking LLM calls.

## Installation

```bash
pip install apexagents
```

## Quickstart

```python
import asyncio
from apexagents import Agent, tool

@tool
def calculate_sum(a: int, b: int) -> int:
    """Calculates the sum of two integers."""
    return a + b

async def main():
    agent = Agent(
        name="MathBot",
        model="gpt-4o-mini",
        instructions="You are a helpful math assistant. Use tools for calculations.",
        tools=[calculate_sum]
    )
    
    response = await agent.arun("Can you add 256 and 512 for me?")
    print(response)

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

## Core Capabilities

### 1. Advanced Memory Management
`apexagents` supports persistent memory out-of-the-box. You can use `SQLiteMemory` for persistence and `SummarizingMemory` to handle context window limits.

```python
from apexagents.memory import SQLiteMemory, SummarizingMemory

# Persistent SQLite backend
sqlite_memory = SQLiteMemory(db_path="agent_memory.db", session_id="user_1")

# Wrap with summarization to keep context lean
memory = SummarizingMemory(
    backend=sqlite_memory,
    max_messages=10,
    summarize_down_to=3
)

agent = Agent(..., memory=memory)
```

### 2. MCP Integration (Model Context Protocol)
Connect your agents to standard MCP servers to dynamically fetch tools.

```python
from apexagents import Agent, MCPServerClient

async def main():
    # Connect to a local MCP server
    mcp_client = MCPServerClient(command="npx", args=["-y", "@modelcontextprotocol/server-fetch"])
    await mcp_client.connect()
    
    # Get tools from the server
    external_tools = await mcp_client.get_tools()
    
    agent = Agent(
        model="gpt-4o",
        tools=external_tools
    )
    
    await agent.arun("Fetch the contents of https://example.com")
    await mcp_client.close()
```

## Environment Variables
The framework uses `litellm` under the hood. Ensure you set the relevant API keys for your provider:
- `OPENAI_API_KEY`
- `ANTHROPIC_API_KEY`
- `AZURE_API_KEY`, `AZURE_API_BASE`, `AZURE_API_VERSION`

## License
MIT
