Troubleshooting AI Agent PHP: Solusi Error Umum

<?php

namespace App\Logging;

use Monolog\Logger;
use Monolog\Handler\RotatingFileHandler;
use Monolog\Formatter\JsonFormatter;
use Throwable;

class AgentDiagnosticLogger
{
    private Logger $logger;

    public function __construct(string $logPath = '/home/infokoding/infocoding/writable/logs/ai_agent_error.log')
    {
        $this->logger = new Logger('ai_agent_telemetry');

        // 1. Handler file rotasi harian dengan retensi 14 hari
        $handler = new RotatingFileHandler($logPath, 14, Logger::DEBUG);

        // 2. Format output sebagai JSON baris tunggal (NDJSON) untuk agregator log
        $formatter = new JsonFormatter(JsonFormatter::BATCH_MODE_NEWLINES, true);
        $handler->setFormatter($formatter);

        $this->logger->pushHandler($handler);
    }

    /**
     * Mencatat detail kegagalan API LLM (401, 429, Timeout) dengan konteks JSON lengkap.
     */
    public function logApiFailure(string $endpoint, int $httpCode, string $rawError, array $extraContext = []): void
    {
        $payload = array_merge([
            'timestamp'   => date('Y-m-d H:i:s'),
            'environment' => $_ENV['CI_ENVIRONMENT'] ?? 'production',
            'endpoint'    => $endpoint,
            'http_code'   => $httpCode,
            'error_raw'   => $rawError,
        ], $extraContext);

        if ($httpCode === 401) {
            $this->logger->critical('LLM_AUTH_FAILED: Kunci API tidak valid atau kedaluwarsa.', $payload);
        } elseif ($httpCode === 429) {
            $this->logger->warning('LLM_RATE_LIMITED: Batas kuota TPM/RPM tercapai, memicu retry.', $payload);
        } elseif ($httpCode === 0 || $httpCode === 504) {
            $this->logger->error('LLM_SOCKET_TIMEOUT: Sambungan cURL terputus sebelum agen selesai merespons.', $payload);
        } else {
            $this->logger->error('LLM_UNEXPECTED_ERROR: Terjadi anomali pada pemanggilan LLM.', $payload);
        }
    }
}

{"error": {"code": "invalid_api_key", "message": "Incorrect API key provided: sk-proj-***"}}

<?php
// Validasi sanitasi kunci API OpenAI sebelum runtime
function validateApiKeyPrefix(string $apiKey): string
{
    $cleanKey = trim($apiKey);
    if (!str_starts_with($cleanKey, 'sk-')) {
        throw new \InvalidArgumentException("Format API Key tidak valid. Kunci harus diawali 'sk-'.");
    }
    return $cleanKey;
}

{"error": {"code": "rate_limit_exceeded", "message": "You exceeded your current quota, please check your plan."}}

<?php

function executeWithExponentialBackoff(callable $callback, int $maxRetries = 3): mixed
{
    for ($attempt = 1; $attempt <= $maxRetries; $attempt++) {
        try {
            return $callback();
        } catch (\Throwable $e) {
            if (str_contains($e->getMessage(), '429') && $attempt < $maxRetries) {
                // Formula: 2^attempt + random jitter (0-1 detik)
                $delaySec = (2 ** $attempt) + (random_int(100, 1000) / 1000);
                usleep((int)($delaySec * 1_000_000));
                continue;
            }
            throw $e;
        }
    }
    throw new \RuntimeException("Batas maksimum retry tercapai.");
}

<?php
// Konfigurasi timeout cURL optimal untuk agen multi-tools
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_CONNECTTIMEOUT => 10,  // Maksimal 10 detik untuk handshake
    CURLOPT_TIMEOUT        => 120, // 120 detik untuk proses ReAct loop penuh
    CURLOPT_TCP_KEEPALIVE  => 1,
]);

<?php

namespace App\MCP;

use RuntimeException;

class SafeMcpTransport
{
    /**
     * Membuka koneksi STDIO ke server MCP secara aman dengan error guard.
     */
    public static function executeMcpCommand(string $binaryPath, string $serverScript, array $jsonPayload): array
    {
        // 1. Pastikan path executable absolut
        if (!file_exists($binaryPath)) {
            throw new RuntimeException("Binary runtime tidak ditemukan: {$binaryPath}");
        }

        $cmd = escapeshellcmd("{$binaryPath} {$serverScript}");
        $descriptors = [
            0 => ['pipe', 'r'], // STDIN
            1 => ['pipe', 'w'], // STDOUT
            2 => ['pipe', 'w'], // STDERR
        ];

        $process = proc_open($cmd, $descriptors, $pipes);
        if (!is_resource($process)) {
            throw new RuntimeException("Gagal menginisialisasi sub-process MCP Server.");
        }

        // 2. Kirim pesan JSON-RPC
        fwrite($pipes[0], json_encode($jsonPayload) . "\n");
        fclose($pipes[0]);

        // 3. Baca STDOUT & tangkap STDERR
        $output = stream_get_contents($pipes[1]);
        $errors = stream_get_contents($pipes[2]);
        fclose($pipes[1]);
        fclose($pipes[2]);

        $exitCode = proc_close($process);
        if ($exitCode !== 0 || empty($output)) {
            throw new RuntimeException("MCP Server crash dengan exit code {$exitCode}. Detail: {$errors}");
        }

        $decoded = json_decode($output, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new RuntimeException("Respons MCP Server bukan JSON-RPC valid: " . substr($output, 0, 100));
        }

        return $decoded;
    }
}

{"error": {"code": "context_length_exceeded", "message": "This model maximum context length is 128000 tokens..."}}

<?php
// Pemangkas riwayat percakapan otomatis berbasis sliding window
function pruneConversationContext(array $history, int $maxAllowedTurns = 8): array
{
    if (count($history) <= $maxAllowedTurns) {
        return $history;
    }
    // Ambil N pesan terakhir untuk menjaga batas konteks token
    return array_slice($history, -$maxAllowedTurns);
}