Console Agent

A PHP-based AI agent management system that executes workflow-driven tasks using OpenAI's API

ConsoleAgent is a powerful framework for creating and executing AI-powered workflows through YAML configuration files. Define complex multi-step processes with conditional logic, user interactions, file operations, and LLM integration - all through simple configuration files.

✨ Features

• 📝 YAML-Driven Workflows: Define complex multi-step processes in simple YAML files
• 🤖 OpenAI Integration: Built-in support for GPT models with configurable parameters
• 🔄 Conditional Logic: Dynamic workflow routing based on user input and context variables
• 👤 Interactive Prompts: Collect user input through various UI components (text, radio, multi-choice)
• 📁 File Operations: Read from and write to files during workflow execution
• 🔄 Iteration Support: Process arrays and lists with per-item actions
• 🌐 MCP Support: Model Context Protocol integration for extended capabilities
• 🎯 Context Management: Share variables between workflow steps with template syntax
• 🧪 Testing: Comprehensive test suite with Pest framework
• 🛠️ Debug Mode: Built-in debugging and dry-run capabilities

🚀 Quick Start

Prerequisites

• PHP 8.3 or higher
• Composer
• OpenAI API key

Installation

1. Clone the repository:

   git clone https://github.com/mwguerra/console-agent.git
   cd console-agent
   

2. Install dependencies:

   composer install
   

3. Set up environment:

   cp .env.example .env
   # Edit .env and add your OpenAI API key
   echo "OPENAI_API_KEY=your-api-key-here" >> .env
   

4. Run an example agent:

   php agent agents/project-documentation.yaml
   

📋 Usage

Basic Command Structure

# Run an agent
php agent path/to/agent.yaml

# Debug mode (shows detailed execution info)
php agent path/to/agent.yaml --debug

# Dry run (shows what would happen without executing)
php agent path/to/agent.yaml --dry-run

Creating Your First Agent

Create a YAML file in the agents/ directory:

# agents/my-agent.yaml
agent:
  name: "MyAgent"
  description: "A simple example agent"
  version: "1.0.0"

llm:
  model: "gpt-4o-mini"
  temperature: 0.7
  max_tokens: 1500

workflow:
  steps:
    - id: step_1
      name: "Get User Input"
      action:
        type: user_input
        input_type: text
        prompt: "What would you like to document?"
        output:
          type: text
          store_as: user_response
      next_step: step_2

    - id: step_2
      name: "Process with LLM"
      action:
        type: llm
        prompt: "Based on this input: {{ user_response }}, create a brief summary."
        output:
          type: text
          store_as: summary
      next_step: step_3

    - id: step_3
      name: "Save Result"
      action:
        type: file_write
        path: "output/summary.md"
        content: "# Summary\n\n{{ summary }}"

🏗️ Architecture

Core Components

• ConsoleAgent.php: Main orchestrator that loads configurations and executes workflows
• WorkflowRunner: Handles step-by-step execution with conditional logic
• ActionRegistry: Manages available action types (LLM, user input, file operations, etc.)
• Context: Maintains variables and state across workflow steps
• Services: LLM and MCP service integrations

Action Types

Action Type	Description	Example Use Case
user_input	Collect user input via prompts	Gathering project requirements
llm	Call OpenAI API with prompts	Content generation, analysis
file_write	Write content to files	Saving generated documentation
file_read	Read file contents	Loading templates or data
display	Show messages to user	Progress updates, results
script	Execute shell commands	Project analysis, file operations
mcp	Model Context Protocol calls	Extended AI capabilities
iteration	Loop over arrays/lists	Processing multiple items

Context Variables

Use {{ variable_name }} syntax to reference context variables:

- action:
    type: llm
    prompt: "Analyze this project: {{ project_description }}"
    output:
      store_as: analysis

Conditional Workflow

next_steps:
  - step: approve_step
    condition: "{{ user_decision }} == 'approve'"
  - step: modify_step
    condition: "{{ user_decision }} == 'modify'"
  - step: exit_step
    condition: "{{ user_decision }} == 'cancel'"

📁 Project Structure

console-agent/
├── agents/                 # YAML agent configurations
│   ├── project-documentation.yaml
│   ├── project-analyzer.yaml
│   └── docs-via-mcp.yaml
├── src/                    # Core PHP classes
│   ├── Actions/           # Action implementations
│   ├── Console/           # Console interface and utilities
│   ├── Core/              # Core workflow components
│   └── Services/          # External service integrations
├── config/                # Configuration files
├── tests/                 # Test suite
├── output/                # Generated files output directory
└── vendor/                # Composer dependencies

🧪 Testing

Run the comprehensive test suite:

# Run all tests
composer test
# or
vendor/bin/pest

# Run specific test categories
vendor/bin/pest tests/Feature/
vendor/bin/pest tests/Unit/Services/

# Run with coverage
vendor/bin/pest --coverage

Test Categories

• Feature Tests: End-to-end agent execution scenarios
• Unit Tests: Individual component testing
• Service Tests: OpenAI and MCP service integration tests
• Action Tests: Individual action type validation

📖 Examples

The project includes several example agents:

1. Project Documentation Agent

File: agents/project-documentation.yaml

• Collects project details from user
• Generates comprehensive documentation
• Creates structured markdown files

2. Project Analyzer Agent

File: agents/project-analyzer.yaml

• Analyzes existing codebases
• Identifies project structure and dependencies
• Generates technical documentation

3. MCP Documentation Agent

File: agents/docs-via-mcp.yaml

• Demonstrates MCP (Model Context Protocol) integration
• Advanced AI capabilities beyond standard LLM calls

⚙️ Configuration

Environment Variables

OPENAI_API_KEY=your-openai-api-key
DEBUG=false
DRY_RUN=false

Agent Configuration

agent:
  name: "Agent Name"
  description: "What this agent does"
  version: "1.0.0"

llm:
  model: "gpt-4o-mini"        # OpenAI model to use
  temperature: 0.7            # Creativity level (0.0-1.0)
  max_tokens: 1500           # Maximum response length

workflow:
  steps:
  # Define your workflow steps here

🔒 Security Notes

• Environment Variables: API keys are loaded from .env file (not committed to version control)
• File Operations: Limited to output/ directory by convention
• Input Validation: User inputs are validated before processing
• ⚠️ Important: The system uses eval() for condition evaluation (line 224 in ConsoleAgent.php) - exercise caution in production environments

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: composer test
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Follow PSR-12 coding standards
• Add tests for new features
• Update documentation for significant changes
• Use semantic commit messages

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: See example agents in agents/ directory
• Email: mwguerra@gmail.com

🙏 Acknowledgments

• OpenAI for providing the AI capabilities
• Laravel Prompts for the beautiful console interface
• Pest PHP for the elegant testing framework
• The PHP community for excellent packages and tools

---

Made with ❤️ by MWGuerra