README

MyAgent is a sophisticated PHP-based deep-research agent that uses recursive intelligence and iterative refinement to solve complex tasks. Powered by OpenAI's GPT models, it combines search, thinking, evaluation, and memory to produce high-quality solutions.

✨ Features

Iterative Refinement: Repeatedly improves solutions until achieving high confidence scores
Multi-Model Intelligence: Uses specialized GPT models for different cognitive functions
Memory Management: Maintains context across iterations with intelligent memory system
Self-Evaluation: Objectively scores its own solutions on a 0-10 scale
Feedback Loop: Generates constructive feedback to guide improvement
Persistence: Continues refining until reaching a perfect score or maximum attempts
PDF Reports: Automatically generates and saves final reports as PDF files
Configurable: Easily customize models and settings through configuration file

🚀 Installation

As a Composer Package

Install via Packagist:

composer require tim.alexander/myagent

From Source

Clone the repository:

git clone https://github.com/TimAnthonyAlexander/myagent.git
cd myagent

Install dependencies:
```
composer install
```

Configure your OpenAI API key (one of these methods):

a. Create a config file:

mkdir -p config
echo "your-openai-api-key" > config/openai.txt

b. Pass it as a command line argument:

php public/runagent.php --api-key=your-openai-api-key "Your task"

c. Set it programmatically:

$agent = new Agent();
$agent->setApiKey('your-openai-api-key');

Configure models (optional):

# The models.json file will be created automatically with defaults
# You can edit it to customize which models are used

💻 Usage

Basic Usage

<?php

require 'vendor/autoload.php';

use TimAlexander\Myagent\Agent\Agent;

// Create agent with API key
$agent = new Agent('your-openai-api-key');
// Or set it later
// $agent->setApiKey('your-openai-api-key');

// Run a task with automatic context gathering (interactive mode)
$agent = new Agent('your-openai-api-key', interactive: true);
$agent->run("Generate a comprehensive marketing plan for a new mobile app");

// Or provide context directly (non-interactive mode)
$agent = new Agent('your-openai-api-key', interactive: false);
$context = "The app is a fitness tracker targeting young professionals. Budget is $50k for marketing. Need to focus on social media and influencer marketing.";
$result = $agent->run("Generate a comprehensive marketing plan for a new mobile app", $context);

// Access the results
echo $result->final_result->report; // The generated report in Markdown
echo $result->final_result->pdf_path; // Path to the generated PDF

The run() method returns a stdClass object with the following structure:

{
    "task": Task,           // The Task object containing the original task and metadata
    "memory": Memory,       // The Memory object containing all gathered information
    "final_result": {       // Present if task completed successfully
        "report": string,   // The final report in Markdown format
        "pdf_path": string  // Full path to the generated PDF file
    },
    "best_solution": string // Present if task didn't reach target score
}

When you run a task, the agent will:

If no context is provided:
- In interactive mode: Ask you clarifying questions to gather more context
- In non-interactive mode: Skip the questions phase
If context is provided:
- Skip the interactive questions phase
- Use the provided context directly
The agent will then process your task through multiple iterations:
- Search for relevant information
- Develop solution approaches
- Evaluate and refine the solution
- Generate a final comprehensive report
The final report will be saved as a PDF in the reports directory

Command Line

The command-line interface always uses interactive mode:

# Using API key from config file
php public/runagent.php "Generate a comprehensive marketing plan for a new mobile app"

# Or specify API key directly
php public/runagent.php --api-key=your-openai-api-key "Generate a comprehensive marketing plan for a new mobile app"

You can also run without arguments to be prompted for input:

php public/runagent.php
Enter task description: Create a Python script to analyze Twitter sentiment

After entering your task, the agent will:

Ask you clarifying questions about your requirements
Wait for your answers (type your response and press Enter twice when done)
Process the task and generate a solution
Save the final report as a PDF in the reports folder

Follow-up Questions

After the task is completed in interactive mode, you can ask follow-up questions about the solution. The agent maintains context from the original task and can provide additional insights or clarifications. Type 'exit' to end the conversation.

⚙️ Configuration

MyAgent uses a configuration file (config/models.json) to customize its behavior:

{
  "models": {
    "default": "gpt-4.1",              // Main processing model
    "evaluation": "gpt-4.1-mini",      // Solution evaluation model
    "search": "gpt-4o-mini-search-preview", // Information gathering model
    "thinking": "o4-mini",             // Solution development model
    "thinking_advanced": "o4-mini"     // Advanced solution development
  },
  "api": {
    "endpoint": "https://api.openai.com/v1/chat/completions",
    "timeout_ms": 120000
  },
  "generation": {
    "max_tokens": 2200,                // Max tokens for standard responses
    "max_completion_tokens": 20000,    // Max tokens for thinking models
    "default_temperature": 0.2         // Lower = more deterministic responses
  },
  "execution": {
    "max_attempts": 5,                 // Maximum solution refinement attempts
    "target_score": 9                  // Target score (0-10) to consider task complete
  }
}

You can adjust these settings to customize:

Which models are used for each cognitive function
API endpoint and timeout settings
Token limits and temperature
Maximum attempts and target score

🧠 How It Works

Task Input: The system accepts a natural language task description
Search Phase: Gathers relevant information for solving the task
Thinking Phase: Develops a solution approach based on gathered information
Evaluation: Assesses the solution quality on a 0-10 scale
Feedback: Generates specific improvement suggestions if needed
Iteration: Repeats the process, refining the solution until reaching a perfect score or maximum attempts
Final Output: Delivers the highest quality solution
PDF Generation: Saves the final report as a PDF in the reports folder

📋 Example Tasks

"Research the impact of AI on healthcare and summarize key findings"
"Create a Python script to analyze Twitter sentiment"
"Design a database schema for an e-commerce platform"
"Write a detailed business plan for a SaaS startup"
"Develop an algorithm to solve the traveling salesman problem"

⚙️ Architecture

┌────────────┐     ┌────────────┐     ┌────────────┐
│   Search   │────▶│  Thinking  │────▶│ Evaluation │
│    GPT     │     │    GPT     │     │    GPT     │
└────────────┘     └────────────┘     └────────────┘
       │                  │                  │
       │                  │                  │
       ▼                  ▼                  ▼
┌─────────────────────────────────────────────────┐
│                     Memory                       │
└─────────────────────────────────────────────────┘
                         │
                         │
                         ▼
┌─────────────────────────────────────────────────┐
│                 Final Response                   │
└─────────────────────────────────────────────────┘
                         │
                         │
                         ▼
┌─────────────────────────────────────────────────┐
│                   PDF Report                     │
└─────────────────────────────────────────────────┘

🛠️ Requirements

PHP 8.1 or higher
Valid OpenAI API key
Composer

📄 License

MIT License

Developed with ❤️ by Tim Anthony Alexander

tim.alexander / myagent

Maintainers

Details