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
UsageMeterkeeps state in a static. The package ships a PHPStan rule,NoWorkerUnsafeNeuronRule, that flags these, along with any provider built without aNeuronHttpClient.Nothing is sent twice. Chat calls are
POSTrequests, 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.