Acton Agent

A lightweight, flexible Python framework for building LLM agents with tool execution capabilities

⚠️ Experimental Project: This is a personal project currently in an experimental phase. The API may change without notice, and features may be incomplete or unstable. Use at your own discretion.

Acton Agent enables you to build AI agents that can interact with external APIs, execute custom Python functions, and maintain conversation context. With minimal configuration, you can create agents that reason through complex tasks, call tools, and stream responses in real-time.

Quick Start

pip install acton-agent

from acton_agent import Agent, FunctionTool
from acton_agent.client import OpenAIClient

# Create a simple calculator tool
def calculate(a: float, b: float, operation: str) -> float:
    ops = {"add": a + b, "subtract": a - b, "multiply": a * b, "divide": a / b}
    return ops.get(operation, 0)

# Initialize agent with OpenAI
client = OpenAIClient(api_key="your-key", model="gpt-4o")
agent = Agent(llm_client=client)

# Register the tool
agent.register_tool(FunctionTool(
    name="calculator",
    description="Perform basic arithmetic operations",
    func=calculate,
    schema={
        "type": "object",
        "properties": {
            "a": {"type": "number"},
            "b": {"type": "number"},
            "operation": {"type": "string", "enum": ["add", "subtract", "multiply", "divide"]}
        },
        "required": ["a", "b", "operation"]
    }
))

# Run the agent
result = agent.run("What is 25 multiplied by 4?")
print(result)  # "The result of 25 multiplied by 4 is 100."

Key Features

🔧 Flexible Tool System

Create tools from Python functions, HTTP APIs, or custom classes. Organize related tools with ToolSets and shared configuration.

from pydantic import Field
from acton_agent import ToolSet, FunctionTool
from acton_agent.tools import ConfigSchema

# Define configuration schema
class WeatherConfig(ConfigSchema):
    api_key: str = Field(..., description="API key for weather service")

# Define tools that use an API key
def get_weather(city: str, api_key: str) -> str:
    # api_key will be automatically injected from toolset config
    return f"Weather in {city}: Sunny, 72°F"

def get_forecast(city: str, days: int, api_key: str) -> str:
    return f"{days}-day forecast for {city}"

# Group related tools with shared configuration
weather_tools = ToolSet(
    name="weather",
    description="Weather data tools",
    tools=[
        FunctionTool(
            name="current_weather",
            description="Get current weather for a city",
            func=get_weather,
            schema={
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"]
            }
        ),
        FunctionTool(
            name="forecast",
            description="Get weather forecast",
            func=get_forecast,
            schema={
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "days": {"type": "integer"}
                },
                "required": ["city", "days"]
            }
        )
    ],
    config_schema=WeatherConfig,
)
# Set configuration using update_config()
weather_tools.update_config({"api_key": "secret-api-key"})
agent.register_toolset(weather_tools)

🔄 Automatic Retry & Error Handling

Built-in retry logic with exponential backoff for both LLM calls and tool execution.

from acton_agent.agent import RetryConfig

agent = Agent(llm_client=client, retry_config=RetryConfig(max_attempts=5))

💬 Conversation Memory Management

Automatic token-based history truncation to stay within context limits.

from acton_agent import SimpleAgentMemory

agent = Agent(llm_client=client, memory=SimpleAgentMemory(max_history_tokens=8000))

🌊 Streaming Support

Stream agent responses token-by-token for real-time feedback.

from acton_agent.agent import AgentToken

for event in agent.run_stream("Tell me a story"):
    if isinstance(event, AgentToken):
        print(event.content, end="", flush=True)

🔌 Multi-Provider Support

Works with OpenAI, OpenRouter, and any OpenAI-compatible API.

from acton_agent import OpenRouterClient

client = OpenRouterClient(api_key="your-key", model="anthropic/claude-3-opus")

📝 Configurable Logging

Control logging output with the verbose parameter and customize log levels via environment variables.

# Disable logging (default - no output)
agent = Agent(llm_client=client, verbose=False)

# Enable logging at INFO level
agent = Agent(llm_client=client, verbose=True)

# Set custom log level via environment variable
import os
os.environ['ACTON_LOG_LEVEL'] = 'DEBUG'  # TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL
agent = Agent(llm_client=client, verbose=True)

Documentation

• Getting Started - Installation and first steps
• Core Concepts - Understanding agents, tools, and memory
• API Reference - Complete API documentation
• Examples - Practical examples from basic to advanced

Examples

Explore complete examples in the examples/ directory:

• Function Tools - Wrap Python functions as agent tools
• Custom Tools - Build custom tool classes
• ToolSet Configuration - Use hidden configuration for API keys and credentials

License

MIT License - see LICENSE file for details.

Disclaimer: This is an experimental project. Use at your own risk. No guarantees about stability, security, or fitness for any particular purpose.