CLI Command Tool Documentation

Overview

The CLICommandTool is a meta-tool that enables BDI agents to execute the system's top-level CLI commands through a standardized interface. It acts as a bridge between agent planning and system-level operations, providing controlled access to critical mindX management functions.

File: tools/cli_command_tool.py Class: CLICommandTool Version: 1.0.0 Status: ✅ Active

Architecture

Design Principles

Command Mapping: Maps high-level command names to specific agent methods

Type Safety: Validates command names before execution

Error Handling: Comprehensive error handling with structured responses

Agent Integration: Requires references to MastermindAgent and CoordinatorAgent

Core Components

class CLICommandTool(BaseTool):
    - mastermind: MastermindAgent reference
    - coordinator: CoordinatorAgent reference
    - command_map: Dict[str, Callable] - Maps command names to handlers

Available Commands

1. evolve

Handler: mastermind.manage_mindx_evolution

Purpose: Manages mindX system evolution and improvements

Usage: {"command_name": "evolve", "args": {...}}

2. deploy

Handler: mastermind.manage_agent_deployment

Purpose: Manages agent deployment operations

Usage: {"command_name": "deploy", "args": {...}}

3. agent_create

Handler: coordinator.create_and_register_agent

Purpose: Creates and registers new agents in the system

Usage: {"command_name": "agent_create", "args": {"agent_type": "...", ...}}

4. agent_delete

Handler: coordinator.deregister_and_shutdown_agent

Purpose: Deregisters and shuts down existing agents

Usage: {"command_name": "agent_delete", "args": {"agent_id": "..."}}

5. agent_evolve

Handler: coordinator.handle_user_input (adapted)

Purpose: Evolves an existing agent based on directives

Usage: {"command_name": "agent_evolve", "args": {"id": "...", "directive": "..."}}

Note: Requires special handling to construct Interaction object

Usage

Basic Execution

from tools.cli_command_tool import CLICommandTool
from orchestration.mastermind_agent import MastermindAgent
from orchestration.coordinator_agent import CoordinatorAgent

Initialize tool
tool = CLICommandTool(
    mastermind=mastermind_agent,
    coordinator=coordinator_agent
)

Execute command
result = await tool.execute(
    command_name="evolve",
    args={"directive": "Improve system performance"}
)

Response Format

# Success
{
    "status": "SUCCESS",
    "result": {...}  # Command-specific result
}

Error
{
    "status": "ERROR",
    "message": "Error description"
}

Integration

With BDI Agents

The tool is designed to be used by BDI agents in their planning and execution phases:

# In agent plan
plan = [
    {
        "action": "execute_cli_command",
        "command": "agent_create",
        "args": {"agent_type": "analysis_agent"}
    }
]

With Mastermind Agent

The tool requires active MastermindAgent and CoordinatorAgent instances, making it suitable for high-level orchestration tasks.

Security Considerations

Access Control: Only agents with proper references can use this tool

Command Validation: Unknown commands are rejected

Error Isolation: Errors are caught and returned as structured responses

No Direct System Access: All operations go through agent methods

Limitations & Improvements

Current Limitations

agent_evolve Simplification: The agent_evolve command uses a simplified Interaction object construction

No Command History: No tracking of executed commands

No Validation: Input validation is minimal

Synchronous Dependencies: Requires synchronous agent references

Recommended Improvements

Enhanced Validation: Add input validation for command arguments

Command History: Track executed commands for auditing

Async Initialization: Support async agent initialization

Better Error Messages: More descriptive error messages with context

Command Documentation: Auto-generate command documentation from handlers

Technical Details

Dependencies

core.bdi_agent.BaseTool - Base tool class

orchestration.mastermind_agent.MastermindAgent - Mastermind agent

orchestration.coordinator_agent.CoordinatorAgent - Coordinator agent

Error Handling

All errors are caught and returned as structured error responses:

try:
    result = await handler(**args)
    return {"status": "SUCCESS", "result": result}
except Exception as e:
    logger.error(f"Error executing CLI command '{command_name}': {e}")
    return {"status": "ERROR", "message": str(e)}

Examples

Creating an Agent

result = await tool.execute(
    command_name="agent_create",
    args={
        "agent_type": "analysis_agent",
        "agent_id": "analysis_001",
        "config": {...}
    }
)

Evolving the System

result = await tool.execute(
    command_name="evolve",
    args={
        "directive": "Improve memory management efficiency",
        "focus_areas": ["memory", "performance"]
    }
)

Future Enhancements

Command Chaining: Support for command pipelines

Conditional Execution: Support for conditional command execution

Rollback Support: Ability to rollback command effects

Performance Monitoring: Track command execution times

Command Templates: Pre-defined command templates for common operations

---