Skip to content
Jefferson Gonçalves
← Back to projects

Console Agent

A simple AI agent manager.

#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

#🙏 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

New version available.