Kinetis Neuron 1.0: AI Agents in a Persistent Worker#

Neuron AI gives PHP agents, tools and clients for the major LLM providers. Out of the box, its providers send HTTP with CurlHttpClient, which blocks the process for the whole call. A call can take tens of seconds, so in a persistent worker that’s a long time for nothing else to run. kinetis/neuron 1.0.0 runs Neuron’s providers over the Kinetis HTTP client instead, and adds what an agent needs inside a Kinetis application.

Getting started#

Install the package:

composer require kinetis/neuron

Pass a NeuronHttpClient to the provider:

use Kinetis\Neuron\NeuronHttpClient;
use Kinetis\RevoltHttpClient\Http;
use NeuronAI\Providers\OpenAI\OpenAI;

$client = new NeuronHttpClient(
    new Http()->withTimeout(120)->withMaxResponseBytes(4 * 1024 * 1024),
    'https://api.openai.com/v1',
);

$provider = new OpenAI(key: $apiKey, model: 'gpt-4.1-mini', httpClient: $client);

A provider call now suspends the calling Fiber instead of blocking the process, so timers and other I/O in the same request keep running. withTimeout() bounds the whole call, a streamed answer included, and withMaxResponseBytes() bounds the body. The second argument is the provider’s base URI: any other absolute URI is refused before anything is sent, so the API key can reach only the provider.

The client is immutable and holds no request data, so build it once at boot. The provider and the Agent do hold request data, the system prompt, the tools and the chat history, so build those per request. The Neuron guide shows the full path from a route to an agent.

Your own tools#

An agent can call the application’s own #[McpTool] methods in process, with no MCP connection:

$agent->addTool($mcpTools->select('find_orders', 'cancel_order'));

Each tool runs with the current request’s identity and request-scoped services, as it would over MCP. The model sees the tool’s MCP input schema unchanged, and the MCP dispatcher validates its arguments. When the arguments are wrong, the model gets the same error feedback an MCP client would, so it can fix its next call.

A remote MCP server works too. Neuron’s McpConnector takes a NeuronHttpClient, which keeps its token on the server’s origin and bounds every response.

Streaming to the browser#

AgentStream sends an agent run to the browser as Server-Sent Events, in the Vercel AI SDK protocol for useChat or in AG-UI:

$adapter = new VercelAIAdapter();
$run = $agent->setStreamAdapter(static fn (): VercelAIAdapter => $adapter)
    ->stream(new UserMessage($question));

return new AgentStream($adapter)->response($run);

Each protocol event is flushed as it happens. If the run fails partway, the browser gets the protocol’s error event with a neutral message, never the exception text. Streaming works under FrankenPHP and PHP-FPM.

Tracing inference#

$agent = InferenceTelemetry::observe(Agent::make())->setAiProvider($provider);

With kinetis/telemetry exporting, each provider call becomes a chat {model} span with the provider, the model and the token usage, named the way OpenTelemetry’s GenAI conventions name them. The prompt and the answer never go into the span.

Things to know#

  • Some Neuron features don’t belong in a worker. Parallel tool calls fork the process, the file and PDO stores block, the stdio and SSE MCP transports block, and UsageMeter keeps state in a static. The package ships a PHPStan rule, NoWorkerUnsafeNeuronRule, that flags these, along with any provider built without a NeuronHttpClient.

  • Nothing is sent twice. Chat calls are POST requests, and neither the client nor this package retries them. After a timeout, the provider may still have run, and billed, the call.

  • Error messages can quote the prompt. A provider’s error body can echo request content, so treat it like request data before you log it.

  • RoadRunner can’t stream. It answers a streamed response with 501. Plain JSON answers work on every runtime.

Upgrading#

Install kinetis/neuron 1.0.0. It requires neuron-core/neuron-ai 4.1.24 or later. It ships with kinetis/framework 1.28.0, kinetis/mcp 1.9.0 and kinetis/telemetry 1.7.0; update those too to use the in-process tools and inference spans.