axm-agent 0.2.3

A simple, elegant Python framework for building AI agents with decorators, MCP support, and powerful utilities

🤖 AXM Agent

A simple, elegant Python framework for building AI agents with decorators, MCP support, and powerful utilities

✨ Why AXM Agent?

AXM Agent is designed with simplicity and developer experience in mind. Unlike heavyweight frameworks, AXM Agent lets you build powerful AI agents with just a few lines of code using elegant decorators and intuitive APIs.

from axm import Agent, tool

# Create an agent
agent = Agent("gpt-4")

# Define tools with a simple decorator
@agent.tool
def get_weather(city: str) -> str:
    """Get the weather for a city"""
    return f"Sunny in {city}"

# Run the agent
response = agent.run("What's the weather in Paris?")
print(response)

🚀 Features

• 🎯 Simple Decorator API - Define tools and agents with intuitive decorators
• 🔌 MCP Support - Full Model Context Protocol integration
• 📞 Function Calling - Automatic function calling with type validation
• 📋 Planning & Scheduling - Built-in task planning and execution
• ✅ Format-Constrained Output - JSON, Pydantic models, and custom schemas
• ⚡ Async & Streaming - Full async support with streaming responses
• 🎨 Multi-Agent Systems - Easy collaboration between multiple agents
• 🔄 Memory & Context - Conversation memory and context management
• 🛠️ Multiple LLM Support - OpenAI, Anthropic, and custom providers
• 📊 Observable - Built-in logging and tracing

📦 Installation

pip install axm-agent

For OpenAI support:

pip install axm-agent[openai]

For Anthropic (Claude) support:

pip install axm-agent[anthropic]

For all providers:

pip install axm-agent[all]

🔑 Configuration

AXM Agent uses environment variables for API credentials:

OpenAI

export AXM_OPENAI_API_KEY="sk-..."

Anthropic (Claude)

export AXM_ANTHROPIC_API_KEY="sk-ant-..."

OpenAI-Compatible Providers (DeepSeek, local LLMs, etc.)

export AXM_OPENAI_COMPATIBLE_API_KEY="your-api-key"
export AXM_OPENAI_COMPATIBLE_BASE_URL="https://your-endpoint.com/v1"

You can also pass credentials directly when creating agents:

agent = Agent("gpt-4", api_key="sk-...", base_url="https://custom-endpoint.com/v1")

🎓 Quick Start

Basic Agent

from axm import Agent

agent = Agent("gpt-4")
response = agent.run("Tell me a joke")
print(response)

Agent with Tools

from axm import Agent, tool
import datetime

agent = Agent("gpt-4")

@agent.tool
def get_current_time() -> str:
    """Get the current time"""
    return datetime.datetime.now().strftime("%H:%M:%S")

@agent.tool
def calculate(expression: str) -> float:
    """Safely evaluate a mathematical expression"""
    return eval(expression, {"__builtins__": {}})

response = agent.run("What time is it and what is 25 * 4?")
print(response)

Structured Output

from axm import Agent
from pydantic import BaseModel

class WeatherReport(BaseModel):
    city: str
    temperature: float
    conditions: str
    humidity: int

agent = Agent("gpt-4")
report = agent.run(
    "Generate a weather report for Paris",
    response_format=WeatherReport
)
print(f"{report.city}: {report.temperature}°C, {report.conditions}")

Planning Agent

from axm import PlanningAgent

agent = PlanningAgent("gpt-4")

# The agent will break down the task into steps and execute them
result = agent.execute_plan(
    "Research the top 3 programming languages in 2025 and create a comparison"
)

Multi-Agent System

from axm import Agent, MultiAgent

researcher = Agent("gpt-4", role="researcher")
writer = Agent("gpt-4", role="writer")
critic = Agent("gpt-4", role="critic")

team = MultiAgent([researcher, writer, critic])
result = team.collaborate("Write an article about AI agents")

Async Support

from axm import Agent
import asyncio

async def main():
    agent = Agent("gpt-4")

    # Async execution
    response = await agent.arun("Tell me about async programming")

    # Streaming
    async for chunk in agent.stream("Write a story"):
        print(chunk, end="", flush=True)

asyncio.run(main())

MCP Integration

from axm import Agent
from axm.mcp import MCPServer

# Create an MCP server
mcp = MCPServer()

@mcp.tool
def search_database(query: str) -> list:
    """Search the database"""
    return ["result1", "result2"]

# Connect agent to MCP
agent = Agent("gpt-4", mcp_server=mcp)
response = agent.run("Search for user data")

📚 Advanced Features

Custom LLM Provider

from axm import Agent, LLMProvider

class CustomLLM(LLMProvider):
    def generate(self, messages, **kwargs):
        # Your custom LLM logic
        pass

agent = Agent(CustomLLM())

Memory Management

from axm import Agent
from axm.memory import ConversationMemory

agent = Agent("gpt-4", memory=ConversationMemory(max_messages=10))

agent.run("My name is Alice")
agent.run("What's my name?")  # Will remember "Alice"

Retry & Error Handling

from axm import Agent

agent = Agent("gpt-4", max_retries=3, timeout=30)

@agent.tool
def risky_operation() -> str:
    """An operation that might fail"""
    # Will automatically retry on failure
    pass

🏗️ Architecture

AXM Agent is built on three core principles:

1. Simplicity First - Easy things should be easy, complex things should be possible
2. Type Safety - Full Pydantic integration for validation
3. Composability - Mix and match components to build what you need

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Inspired by the best ideas from LangChain, CrewAI, and AutoGen, but designed for simplicity.

📖 Documentation

For full documentation, visit our docs

🐛 Issues

Found a bug? Please open an issue