beast-agent 0.1.3

Base agent class for all Beast Mode agents

Beast Agent

Base agent class for ALL Beast Mode agents

---

🎯 Purpose

The foundational base class (BaseAgent) that EVERY Beast Mode agent inherits from.

This package provides:

• ✅ Standardized agent lifecycle (startup, shutdown, health checks)
• ✅ Message handling via beast-mailbox-core integration
• ✅ Agent registration and discovery
• ✅ Capability declaration and management
• ✅ Optional logging/telemetry hooks
• ✅ Configuration management

Architectural Clarity:

• beast-agent = Low-level base class (every agent IS-A beast-agent)
• beast-agentic-framework = High-level orchestration (multi-agent coordination)

---

🚀 Quick Start

Installation

pip install beast-agent

Configuration

Configure Redis connection via environment variable:

export REDIS_URL="redis://localhost:6379"

Or pass directly to constructor (see examples below).

Create Your First Agent

from beast_agent import BaseAgent
from beast_agent.decorators import capability

class MyAgent(BaseAgent):
    """Simple agent with a single capability"""
    
    def __init__(self):
        super().__init__(
            agent_id="my-agent",
            capabilities=["process_data"]
        )
    
    @capability("process_data")
    async def process_data(self, data: dict) -> dict:
        """Process data and return results"""
        # Your agent logic here
        return {"status": "processed", "result": data}

# Run the agent
async def main():
    agent = MyAgent()
    await agent.startup()
    # Agent is now ready to handle messages
    
if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

---

🔐 Connecting with Authentication

If your Redis cluster requires authentication, use MailboxConfig instead of a URL string:

from beast_agent import BaseAgent
from beast_mailbox_core import MailboxConfig
import os

class AuthenticatedAgent(BaseAgent):
    """Agent that connects to authenticated Redis cluster."""
    
    def __init__(self):
        # Create MailboxConfig with password
        mailbox_config = MailboxConfig(
            host=os.getenv("REDIS_HOST", "localhost"),
            port=int(os.getenv("REDIS_PORT", "6379")),
            password=os.getenv("REDIS_PASSWORD"),  # Required for authenticated clusters
            db=0
        )
        
        super().__init__(
            agent_id="authenticated-agent",
            capabilities=["example"],
            mailbox_url=mailbox_config  # Pass MailboxConfig object, not URL string
        )
    
    async def on_startup(self) -> None:
        self._logger.info("Connected to authenticated cluster!")
    
    async def on_shutdown(self) -> None:
        self._logger.info("Disconnecting...")

Note: The mailbox_url parameter accepts:

• String URL: "redis://localhost:6379" (for unauthenticated connections)
• MailboxConfig object: For authenticated or advanced configurations (recommended for production)
• None: Uses REDIS_URL environment variable

For production clusters with authentication, always use MailboxConfig - URL parsing doesn't support passwords in the URL format.

See examples/authenticated_agent.py for a complete example.

---

📋 Agent Patterns

Per-Repo Agent Pattern

class RepoAgent(BaseAgent):
    """Agent that monitors a single repository"""
    
    def __init__(self, repo_name: str):
        super().__init__(
            agent_id=f"repo-agent-{repo_name}",
            capabilities=["code_review", "pr_validation", "security_scan"]
        )
        self.repo_name = repo_name
    
    @capability("code_review")
    async def review_code(self, pr_number: int) -> dict:
        """Review code in PR"""
        # Review logic
        return {"status": "reviewed", "pr": pr_number}

Per-Branch Agent Pattern

class BranchAgent(BaseAgent):
    """Agent specific to a branch"""
    
    def __init__(self, repo_name: str, branch_name: str):
        super().__init__(
            agent_id=f"branch-agent-{repo_name}-{branch_name}",
            capabilities=["deployment", "testing", "monitoring"]
        )
        self.repo = repo_name
        self.branch = branch_name
    
    @capability("deployment")
    async def deploy(self, environment: str) -> dict:
        """Deploy branch to environment"""
        # Deployment logic
        return {"status": "deployed", "environment": environment}

---

🔧 Features

Agent Lifecycle

agent = MyAgent()
await agent.startup()  # Initialize and register
# ... agent is running ...
await agent.shutdown()  # Graceful cleanup

Message Handling

# Register handler for message type
agent.register_handler("TASK_REQUEST", handle_task_request)

# Send message to another agent
await agent.send_message(
    target="other-agent-id",
    message_type="HELP_REQUEST",
    content={"task": "analyze_code"}
)

Health Checks

health = agent.health_check()
print(f"Healthy: {health.healthy}")
print(f"State: {health.state}")

---

📚 Documentation

• Agent Development Guide - How to create custom agents
• Deployment Patterns - Per-repo, per-branch, orchestration
• API Reference - Complete API documentation
• Examples - Example agent implementations

---

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src/beast_agent --cov-report=html

# Run specific test
pytest tests/test_base_agent.py

# Run integration tests (requires Redis and beast-mailbox-core)
# Note: Integration tests are automatically skipped if dependencies unavailable
pytest tests/test_mailbox_integration.py

# Run all tests including integration (if Redis available)
pytest tests/

Integration Testing

Integration tests require:

• Redis: Running locally (via Docker) or in CI (via service containers)
• beast-mailbox-core: Installed as dependency

Local Testing:

• Redis Docker container is automatically managed via conftest.py fixtures
• Tests gracefully skip if Redis/Docker unavailable
• Uses separate test database (db=15) to avoid conflicts

CI Testing:

• Redis service container automatically provided in GitHub Actions
• Integration tests run against real Redis in CI

---

🤝 Integration

Required Dependencies

• beast-mailbox-core >= 0.3.0 - Messaging and discovery

Optional Dependencies

• beast-observability - Enhanced telemetry
• Any cloud platform (works with AWS, GCP, Azure, on-prem)

---

📦 Package Status

Tier: 1 (Foundation)
Phase: Development
Coverage: Target 90%+
Quality: Target zero defects

---

🔗 Related Packages

• beast-mailbox-core - Redis-backed mailbox utilities
• beast-agentic-framework - Multi-agent orchestration
• beast-observability - Unified telemetry
• beast-redaction-client - Data classification

---

📄 License

MIT License - see LICENSE for details.

---

🙏 Acknowledgments

Part of the Beast Mode multi-agent framework ecosystem.

---

Built with ❤️ by the Beast Mode team