Build Local AI Agent Workflows with Ollama and PHP: 2026 Guide28 min read

# Check that Ollama service is running and accessible
curl http://127.0.0.1:11434/api/version

# Pull Llama 3.1 8B with function calling capabilities
ollama pull llama3.1:8b

# Alternatively, pull Qwen 2.5 7B which excels at structured JSON schemas
ollama pull qwen2.5:7b

curl -X POST http://127.0.0.1:11434/api/generate -d '{
  "model": "llama3.1:8b",
  "prompt": "Respond with the word READY",
  "stream": false
}'

mkdir local-php-agent
cd local-php-agent
composer init --no-interaction
composer require guzzlehttp/guzzle:^7.8

mkdir -p src/Tools

<?php

declare(strict_types=1);

namespace App;

use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;
use RuntimeException;

class OllamaClient
{
    private Client $httpClient;
    private string $model;

    public function __construct(
        string $baseUri = 'http://127.0.0.1:11434',
        string $model = 'llama3.1:8b',
        float $timeout = 120.0
    ) {
        $this->model = $model;
        $this->httpClient = new Client([
            'base_uri' => rtrim($baseUri, '/') . '/',
            'timeout'  => $timeout,
            'headers'  => [
                'Content-Type' => 'application/json',
                'Accept'       => 'application/json',
            ],
        ]);
    }

    /**
     * Dispatches a chat completion request with optional tool definitions.
     *
     * @param array $messages Multi-turn conversation history.
     * @param array $tools Function signatures available to the model.
     * @return array Decoded response message payload.
     */
    public function chat(array $messages, array $tools = []): array
    {
        $payload = [
            'model'    => $this->model,
            'messages' => $messages,
            'stream'   => false,
            'options'  => [
                'temperature' => 0.1, // Low temperature ensures deterministic tool calling
                'num_ctx'     => 8192, // Expanded context window for tool schemas
            ],
        ];

        if (!empty($tools)) {
            $payload['tools'] = $tools;
        }

        try {
            $response = $this->httpClient->post('api/chat', [
                'json' => $payload,
            ]);

            $body = (string) $response->getBody();
            $data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

            if (!isset($data['message'])) {
                throw new RuntimeException('Malformed response: missing message key in Ollama payload.');
            }

            return $data['message'];
        } catch (GuzzleException $e) {
            throw new RuntimeException('Ollama communication error: ' . $e->getMessage(), 0, $e);
        } catch (\JsonException $e) {
            throw new RuntimeException('Failed to parse Ollama JSON response: ' . $e->getMessage(), 0, $e);
        }
    }
}

<?php

declare(strict_types=1);

namespace App\Tools;

interface ToolInterface
{
    /**
     * Unique identifier for the tool.
     */
    public function getName(): string;

    /**
     * Detailed description guiding the model on when and how to call the tool.
     */
    public function getDescription(): string;

    /**
     * OpenAI-compatible JSON Schema definition.
     */
    public function getSchema(): array;

    /**
     * Executes the tool with arguments generated by the model.
     *
     * @param array $arguments
     * @return string Result returned to the agent context.
     */
    public function execute(array $arguments): string;
}

<?php

declare(strict_types=1);

namespace App\Tools;

class SystemMetricsTool implements ToolInterface
{
    public function getName(): string
    {
        return 'get_system_metrics';
    }

    public function getDescription(): string
    {
        return 'Retrieves real-time system performance data including disk space, memory usage, and load averages on the host server.';
    }

    public function getSchema(): array
    {
        return [
            'type' => 'function',
            'function' => [
                'name'        => $this->getName(),
                'description' => $this->getDescription(),
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => [
                        'mount_point' => [
                            'type'        => 'string',
                            'description' => 'The filesystem mount path to inspect, such as "/" or "/var/www". Defaults to "/".',
                        ],
                    ],
                    'required'   => [],
                ],
            ],
        ];
    }

    public function execute(array $arguments): string
    {
        $mountPoint = $arguments['mount_point'] ?? '/';
        
        // Sanitize mount path to prevent command injection
        if (!file_exists($mountPoint)) {
            return json_encode([
                'status'  => 'error',
                'message' => "Specified mount point '{$mountPoint}' does not exist.",
            ], JSON_THROW_ON_ERROR);
        }

        $totalSpace = @disk_total_space($mountPoint);
        $freeSpace  = @disk_free_space($mountPoint);

        $totalGb = $totalSpace !== false ? round($totalSpace / (1024 ** 3), 2) : 0.0;
        $freeGb  = $freeSpace !== false ? round($freeSpace / (1024 ** 3), 2) : 0.0;
        $usedGb  = round($totalGb - $freeGb, 2);
        $usagePercent = $totalGb > 0 ? round(($usedGb / $totalGb) * 100, 1) : 0;

        $loadAverage = function_exists('sys_getloadavg') ? sys_getloadavg() : [0.0, 0.0, 0.0];

        return json_encode([
            'status'         => 'success',
            'mount_point'    => $mountPoint,
            'total_space_gb' => $totalGb,
            'used_space_gb'  => $usedGb,
            'free_space_gb'  => $freeGb,
            'usage_percent'  => $usagePercent . '%',
            'load_averages'  => [
                '1_min'  => $loadAverage[0] ?? 0.0,
                '5_min'  => $loadAverage[1] ?? 0.0,
                '15_min' => $loadAverage[2] ?? 0.0,
            ],
            'timestamp'      => date('c'),
        ], JSON_THROW_ON_ERROR);
    }
}

<?php

declare(strict_types=1);

namespace App\Tools;

class LogInspectionTool implements ToolInterface
{
    private string $allowedLogDirectory;

    public function __construct(string $allowedLogDirectory = '/var/log')
    {
        $this->allowedLogDirectory = realpath($allowedLogDirectory) ?: sys_get_temp_dir();
    }

    public function getName(): string
    {
        return 'inspect_recent_logs';
    }

    public function getDescription(): string
    {
        return 'Reads the most recent lines of a specified application or system log file to debug errors and operational warnings.';
    }

    public function getSchema(): array
    {
        return [
            'type' => 'function',
            'function' => [
                'name'        => $this->getName(),
                'description' => $this->getDescription(),
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => [
                        'filename' => [
                            'type'        => 'string',
                            'description' => 'The name of the log file to inspect, e.g., "app.log" or "error.log".',
                        ],
                        'line_count' => [
                            'type'        => 'integer',
                            'description' => 'Number of lines to read from the end of the file. Maximum 50 lines.',
                        ],
                    ],
                    'required'   => ['filename'],
                ],
            ],
        ];
    }

    public function execute(array $arguments): string
    {
        $filename  = basename($arguments['filename'] ?? '');
        $lineCount = min(50, max(1, (int) ($arguments['line_count'] ?? 10)));
        $filePath  = $this->allowedLogDirectory . DIRECTORY_SEPARATOR . $filename;

        if (!file_exists($filePath) || !is_readable($filePath)) {
            return json_encode([
                'status'  => 'error',
                'message' => "Log file '{$filename}' was not found or is unreadable inside allowed directory.",
            ], JSON_THROW_ON_ERROR);
        }

        $lines = file($filePath, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
        if ($lines === false) {
            return json_encode(['status' => 'error', 'message' => 'Could not read log file content.']);
        }

        $tailLines = array_slice($lines, -$lineCount);

        return json_encode([
            'status'     => 'success',
            'filename'   => $filename,
            'line_count' => count($tailLines),
            'lines'      => $tailLines,
        ], JSON_THROW_ON_ERROR);
    }
}

<?php

declare(strict_types=1);

namespace App;

use App\Tools\ToolInterface;
use RuntimeException;

class Agent
{
    private OllamaClient $client;
    /** @var array<string, ToolInterface> */
    private array $tools = [];
    private array $messages = [];
    private int $maxIterations;

    public function __construct(
        OllamaClient $client,
        string $systemPrompt = '',
        int $maxIterations = 6
    ) {
        $this->client = $client;
        $this->maxIterations = $maxIterations;

        $defaultSystemPrompt = 'You are an autonomous systems engineering AI agent running locally in PHP. '
            . 'You solve problems methodically using your available tools. '
            . 'When you need facts or system data, invoke the appropriate tool with precise arguments. '
            . 'After receiving tool observations, review them and synthesize a direct, factual answer. '
            . 'Never guess file contents or hardware statistics if a tool is available.';

        $this->messages[] = [
            'role'    => 'system',
            'content' => !empty($systemPrompt) ? $systemPrompt : $defaultSystemPrompt,
        ];
    }

    /**
     * Registers a tool instance with the agent.
     */
    public function registerTool(ToolInterface $tool): void
    {
        $this->tools[$tool->getName()] = $tool;
    }

    /**
     * Executes the autonomous ReAct reasoning loop.
     *
     * @param string $userPrompt The objective or question submitted by the user.
     * @return string Final response synthesized by the agent.
     */
    public function run(string $userPrompt): string
    {
        $this->messages[] = [
            'role'    => 'user',
            'content' => $userPrompt,
        ];

        $toolSchemas = array_map(fn(ToolInterface $t) => $t->getSchema(), array_values($this->tools));
        $iteration = 0;

        while ($iteration < $this->maxIterations) {
            $iteration++;

            // Query the local Ollama instance with current conversation and tool definitions
            $responseMessage = $this->client->chat($this->messages, $toolSchemas);
            $this->messages[] = $responseMessage;

            // Check if the model decided to execute one or more tools
            $toolCalls = $responseMessage['tool_calls'] ?? [];

            if (empty($toolCalls)) {
                // No tools called; the model has arrived at its final synthesis
                return $responseMessage['content'] ?? 'Agent completed execution with empty content.';
            }

            // Execute each requested tool in sequence
            foreach ($toolCalls as $call) {
                $functionName = $call['function']['name'] ?? '';
                $arguments    = $call['function']['arguments'] ?? [];

                // If arguments were serialized as a JSON string, decode them into an array
                if (is_string($arguments)) {
                    $arguments = json_decode($arguments, true) ?? [];
                }

                if (!isset($this->tools[$functionName])) {
                    $observation = json_encode([
                        'status'  => 'error',
                        'message' => "Tool '{$functionName}' is not registered with this agent.",
                    ]);
                } else {
                    try {
                        $observation = $this->tools[$functionName]->execute($arguments);
                    } catch (\Throwable $e) {
                        $observation = json_encode([
                            'status'  => 'exception',
                            'message' => 'Tool execution failed: ' . $e->getMessage(),
                        ]);
                    }
                }

                // Append the observation back into the context using the "tool" role
                $this->messages[] = [
                    'role'       => 'tool',
                    'content'    => $observation,
                    'name'       => $functionName,
                ];
            }
        }

        throw new RuntimeException("Agent exceeded maximum allowed iterations ({$this->maxIterations}) without resolving.");
    }

    /**
     * Returns the full conversation transcript for auditing.
     */
    public function getHistory(): array
    {
        return $this->messages;
    }
}

<?php

declare(strict_types=1);

namespace App;

class MemoryManager
{
    private int $maxRetainedTurns;

    public function __construct(int $maxRetainedTurns = 10)
    {
        $this->maxRetainedTurns = $maxRetainedTurns;
    }

    /**
     * Compresses the message array by truncating oversized tool observations.
     *
     * @param array $messages
     * @param int $maxObservationChars
     * @return array Pruned messages array.
     */
    public function prune(array $messages, int $maxObservationChars = 1500): array
    {
        if (count($messages) <= 3) {
            return $messages;
        }

        $systemMessage = array_shift($messages);
        $pruned = [];

        foreach ($messages as $msg) {
            if ($msg['role'] === 'tool' && strlen($msg['content']) > $maxObservationChars) {
                // Truncate bulky JSON payloads to prevent context overflow
                $msg['content'] = substr($msg['content'], 0, $maxObservationChars) 
                    . '... [Output truncated by agent memory manager]';
            }
            $pruned[] = $msg;
        }

        // Keep only the most recent N conversational exchanges
        if (count($pruned) > $this->maxRetainedTurns) {
            $pruned = array_slice($pruned, -$this->maxRetainedTurns);
        }

        array_unshift($pruned, $systemMessage);

        return $pruned;
    }
}

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use App\Agent;
use App\OllamaClient;
use App\Tools\LogInspectionTool;
use App\Tools\SystemMetricsTool;

// Initialize Ollama connection pointing to local daemon
$client = new OllamaClient(
    baseUri: 'http://127.0.0.1:11434',
    model: 'llama3.1:8b',
    timeout: 120.0
);

// Instantiate the agent
$agent = new Agent($client, maxIterations: 5);

// Register available capabilities
$agent->registerTool(new SystemMetricsTool());
$agent->registerTool(new LogInspectionTool(__DIR__ . '/storage/logs'));

// Define an operational prompt requiring autonomous tool selection
$prompt = 'Inspect the current disk space on the root mount point. '
    . 'If disk usage is above 70%, warn me immediately. '
    . 'Also check if the system load averages indicate any operational bottlenecks.';

echo "=== Submitting Objective to Local AI Agent ===\n";
echo "Prompt: {$prompt}\n\n";

try {
    $result = $agent->run($prompt);
    echo "=== Agent Final Synthesis ===\n";
    echo $result . "\n";
} catch (\Throwable $e) {
    echo "Agent Execution Error: " . $e->getMessage() . "\n";
}

php run-agent.php