Agent Maxim

AI-powered agent system with intelligent task planning, web search capabilities, and a modern mobile dashboard.

Overview

Agent Maxim is an autonomous AI agent that can:

• Understand complex tasks using natural language processing
• Plan multi-step solutions with automatic tool selection
• Execute web searches with intelligent query enhancement
• Process and analyze information from multiple sources
• Provide structured responses through a clean chat interface

Architecture

The system consists of three main components:

1. Agent Core (agent/)

• Planning System: Breaks down complex goals into executable steps
• Tool Registry: Manages available tools (web_search, web_fetch, etc.)
• Runtime Executor: Handles tool execution with safety guards
• State Management: Tracks agent progress and decisions

2. Bridge API (bridge/)

• FastAPI Server: RESTful API endpoint
• Request Routing: Forces agent-only execution (no direct LLM calls)
• Policy Guards: Security and safety checks
• Run Management: Persistent execution state

3. Dashboard (simple_dashboard.py)

• WhatsApp-style UI: Modern mobile-friendly interface
• Real-time Communication: Direct agent interaction
• Responsive Design: Works on all screen sizes
• Visual Feedback: Loading states, formatted results

Installation

Prerequisites

• Python 3.10+
• pip package manager

Setup

# Clone the repository
git clone <repository-url>
cd agent-maxim

# Install dependencies
pip install -r requirements.txt

Usage

Starting the Backend API

cd bridge
python app.py

The API will start on http://localhost:8000

Starting the Dashboard

python simple_dashboard.py

The dashboard will start on http://localhost:8610

Running the Agent Directly

cd agent
python main.py --goal "найди новости OpenAI"
python main.py --goal "inspect project"
python main.py --goal "create file hello.txt with text hello world"

API Endpoints

POST /runs

Execute a one-shot agent run.

Request:

{
  "goal": "найди новости OpenAI",
  "adapter": "agent"
}

Response:

{
  "run_id": "unique-id",
  "status": "completed",
  "goal": "найди новости OpenAI",
  "adapter": "agent",
  "response": "Agent response..."
}

GET /health

Check server status and adapter configuration.

Features

Intelligent Web Search

• Query Enhancement: Automatically improves search queries
• Context Extraction: Removes instruction prefixes
• Source Filtering: Focuses on quality tech sources
• Result Formatting: Clean presentation of search results

Planning System

• Multi-step reasoning: Breaks down complex tasks
• Tool selection: Chooses appropriate tools automatically
• Fallback handling: Graceful degradation on failures
• State tracking: Maintains execution context

Security & Safety

• Workspace isolation: File operations restricted to workspace
• Command filtering: Prevents dangerous operations
• Policy guards: Input validation and sanitization
• Execution limits: Timeout and resource constraints

Development

Project Structure

agent-maxim/
├── agent/                 # Agent core system
│   ├── core/             # Planning and execution logic
│   ├── runtime/          # Tool execution environment
│   └── main.py           # Direct agent entry point
├── bridge/              # API server
│   ├── api/             # REST endpoints
│   ├── adapters/        # Backend adapters
│   └── app.py           # Server entry point
├── simple_dashboard.py   # Mobile dashboard UI
└── requirements.txt      # Python dependencies

Testing

# Run all tests
pytest

# Run specific tests
pytest tests/test_web_search.py

Configuration

Environment Variables

• OLLAMA_MODEL: Default Ollama model (default: "qwen2.5:7b")
• WORKSPACE_ROOT: Workspace directory for file operations

Dashboard Configuration

The dashboard connects to the backend API at /runs endpoint. Ensure the API server is running before starting the dashboard.

Deployment

Production Server

The system is currently deployed on:

• API: https://openclaw.kotkanagrilli.fi (port 8000)
• Dashboard: https://max-dashboard.kotkanagrilli.fi (port 8610)

Server Setup

# On production server
cd /home/anton/clear
# Start backend
cd bridge && python app.py
# Start dashboard (in separate terminal)
python simple_dashboard.py

Example Use Cases

Web Search

User: "найди новости OpenAI"
Agent: Performs enhanced search for latest OpenAI news
      Returns formatted results with titles, snippets, and URLs

Understanding Projects

User: "inspect project"
Agent: Analyzes codebase structure
      Provides overview of files and directories

Task Planning

User: "create a Python file that calculates factorial"
Agent: Plans steps:
      1. Create file structure
      2. Write factorial function
      3. Add test cases
      Executes steps sequentially

Troubleshooting

Common Issues

Dashboard not connecting to API

• Ensure backend API is running on port 8000
• Check firewall settings
• Verify API endpoint is accessible

Agent not responding

• Check backend logs for errors
• Verify agent dependencies are installed
• Ensure workspace directory exists and is writable

Web search returning poor results

• Check internet connectivity
• Verify search API is accessible
• Review query enhancement logs

Contributing

Contributions are welcome! Please follow these guidelines:

• Use the existing code style (4 spaces, max 100 char lines)
• Add tests for new features
• Update documentation for API changes
• Follow security best practices

License

This project is part of the Agent Maxim system.

Support

For issues and questions:

• Check existing documentation
• Review code comments and docstrings
• Examine execution logs for debugging

---

Agent Maxim - Intelligent AI Agent for Task Automation and Information Retrieval