README

This package provides a lightweight integration of the OpenAI PHP client with Laravel 12, inspired by the OpenAI Agents Python SDK.

Installation

composer require aerobit/openai-agents

Publish the configuration file:

php artisan vendor:publish --tag=config --provider="Aerobit\\OpenaiAgents\\AgentServiceProvider"

Set your OPENAI_API_KEY in the environment file or edit config/agents.php.

Usage

Send a message to the default agent:

php artisan agent:chat "Hello"

You can control the number of turns or provide a system prompt using options:

php artisan agent:chat "Hello" --system="You are helpful" --max-turns=3

You can also resolve the AgentManager service from the container to create agents programmatically.

use Aerobit\OpenaiAgents\AgentManager;

$manager = app(AgentManager::class);
$response = $manager->agent()->chat('Hello world');

The returned Agent instance retains the conversation history, allowing for multi-turn chats:

$agent = $manager->agent();

// First user message
$agent->chat('Hello');

// Follow-up message uses previous context
$reply = $agent->chat('What did I just say?');

The agent can also convert text responses to speech:

$audio = $agent->speak('Hello world');
file_put_contents('output.mp3', $audio);

You can optionally provide a system prompt when constructing the agent:

use Aerobit\OpenaiAgents\Agent;
use OpenAI\OpenAI;

$client = OpenAI::factory()->withApiKey(env('OPENAI_API_KEY'))->make();
$agent = new Agent($client, [], 'You are a helpful assistant.');

For more advanced scenarios you can use the Runner class which loops until the agent returns a final response or a turn limit is reached. Tools and basic handoffs can be registered on the runner:

use Aerobit\OpenaiAgents\Runner;

$runner = new Runner($agent, maxTurns: 3);
$runner->registerTool('echo', fn($text) => $text);
$helper = new Agent($client, [], 'Espanol agente');
$runner->registerAgent('spanish', $helper);
$reply = $runner->run('Start');
// inside the conversation use [[handoff:spanish]] to switch

The runner can request structured JSON output by providing an output schema:

$schema = ['required' => ['done']];
$runner = new Runner($agent, maxTurns: 3, tracer: null, outputType: $schema);
$result = $runner->run('Start'); // returns an associative array

Tools may also be defined with JSON schemas for OpenAI function calling:

$runner->registerFunctionTool('echo', fn(array $args) => $args['text'], [
    'type' => 'object',
    'properties' => ['text' => ['type' => 'string']],
    'required' => ['text'],
]);

// Or let the runner derive the schema automatically
$runner->registerAutoFunctionTool('echo_auto', function (string $text) {
    return $text;
});

If you need non-blocking execution you can run the runner inside a PHP Fiber:

$fiber = $runner->runAsync('Hello');
$fiber->start();
$result = $fiber->getReturn();

You can also stream results as they're generated:

foreach ($runner->runStreamed('Hello') as $chunk) {
    echo $chunk;
}

Voice pipeline

Use the VoicePipeline class to handle audio transcription and text-to-speech in one step:

$pipeline = new VoicePipeline($client, $agent);
$audio = $pipeline->run('input.wav');
file_put_contents('reply.mp3', $audio);

Tracing

The package includes a simple tracing system that lets you observe each turn of a Runner execution. Enable tracing in config/agents.php and register one or more processors to handle trace records:

return [
    // ...
    'tracing' => [
        'enabled' => true,
        'processors' => [
            fn(array $record) => logger()->info('agent trace', $record),
            new \Aerobit\OpenaiAgents\Tracing\HttpProcessor('https://example.com/trace'),
        ],
    ],
];

When enabled, each call to Runner::run() will emit start and end span events as well as per-turn events containing the input and output.

Guardrails

Guardrails let you validate input and output during a run. They can transform the content or throw an exception to stop execution.

use Aerobit\OpenaiAgents\Guardrails\InputGuardrail;
use Aerobit\OpenaiAgents\Guardrails\OutputGuardrail;
use Aerobit\OpenaiAgents\Guardrails\OutputGuardrailException;

$runner->addInputGuardrail(new class extends InputGuardrail {
    public function validate(string $content): string
    {
        return strtoupper($content);
    }
});

$runner->addOutputGuardrail(new class extends OutputGuardrail {
    public function validate(string $content): string
    {
        if (str_contains($content, 'bad')) {
            throw new OutputGuardrailException('Bad content');
        }
        return $content;
    }
});

Configuration

The config/agents.php file allows you to customize the default model and parameters used when interacting with OpenAI. It also contains options to enable tracing and provide custom processors for handling trace data.

License

Released under the MIT license.