Neuronai Studio Laravel Package

Getting Started

digitalelvis/neuronai-studio is the Laravel-facing companion to the NeuronAI agent framework: you keep writing agents as plain PHP classes, and the Studio gives you a browser surface to chat with them, inspect message/tool traces, and iterate on prompts without redeploying.

v3.14.2 is a patch release on the 3.14 line (changelog is a bare compare link, no breaking changes, no deprecations, no new features announced). Treat it as a safe composer update — no code changes required, but re-read the diff if you're pinned with --prefer-lowest.

Minimal path to first value:

composer require digitalelvis/neuronai-studio
php artisan vendor:publish --tag=neuronai-studio-config   # config/neuronai-studio.php
php artisan vendor:publish --tag=neuronai-studio-assets   # only if you want to customise the UI
php artisan migrate                                       # conversation/trace tables, if published

Set at least one provider key (OPENAI_API_KEY, ANTHROPIC_API_KEY, or whatever your agents use) and confirm the Studio is enabled and correctly gated in config/neuronai-studio.php.

First use case: don't build anything new. Take an agent you already have (or the docs' sample agent), register it, and open the Studio playground. A single successful round trip with a visible tool call in the trace is the fastest way to confirm keys, driver, HTTP route, and auth gate are all wired.

Where to look first, in order: the published config file (it's the map of the package), routes/ for the Studio endpoints, then src/Http/Controllers and src/Agents if you need to understand discovery. The README's "registering agents" section is the one you'll return to most.

Implementation Patterns

Agent registration is the central decision. Most teams converge on one of three approaches: explicit listing in config/neuronai-studio.php (predictable, easy to review in a PR, but noisy once you pass ten agents), attribute/interface-based discovery (convenient, but you lose the single-file overview of what's exposed), or a small service provider that registers from a domain enum. Whichever you pick, wrap it so the Studio registry and your application's own factory call the same source of truth — divergence between "what the Studio shows" and "what production runs" is the most common source of confusing bugs with this class of package.

Gate the Studio at the route level, not the view level. Put the Studio routes behind a dedicated middleware group with auth plus a gate. Even in local-only setups, define the gate explicitly so that a misconfigured APP_ENV in staging doesn't expose a playground that can burn API credits. A pattern that works well:

Gate::define('viewNeuronStudio', fn (User $user) => $user->isInternal());

and reference it in the config's middleware key rather than editing published routes.

Proxy production traffic through your own controller. Use the Studio for exploration, but have your application call agents via a thin application-level service (or a queued job) that logs the run. This keeps the Studio as a dev tool and gives you a place for rate limiting, tenant scoping, and cost attribution that the Studio UI has no opinion about.

Persist threads and tie them to your models. If the package ships conversation persistence, add your own user_id/team_id column via a follow-up migration and scope retrieval through a policy. Passing the Studio's thread ID through your frontend lets you resume in the playground while debugging a real user's session.

Stream with SSE, but own the endpoint. Agent responses are slow enough that non-streaming UX feels broken. Terminate the stream in your own controller (or a StreamedResponse) so you control heartbeat comments, error framing, and client disconnect handling; the Studio's own streaming endpoint is fine for the playground but usually too permissive for production.

Long-running runs belong in a queue. Anything with tool loops, RAG retrieval, or multi-step planning will blow past PHP's max_execution_time under web SAPI. Dispatch a job, stream progress over broadcasting or polling, and use the Studio to inspect the resulting trace.

Testing. Assert on your agent's structured output and tool selections rather than free-text completions; stub the provider driver with a fake in the container for CI so your test suite doesn't need a live key. Keep one or two live smoke tests behind a separate group that doesn't run on every push.

Gotchas and Tips

• Config caching bites agent discovery. If registration is config- or discovery-driven, php artisan config:cache in a deploy pipeline can freeze the agent list. Run config:clear/optimize:clear after deploys, or make discovery happen at runtime rather than at boot.
• SSE and proxies. Nginx buffers by default; you need proxy_buffering off and X-Accel-Buffering: no for streaming to feel live. Behind a load balancer, watch idle timeouts on long tool-calling runs.
• Cost surprises come from history, not from model choice. Unbounded conversation growth is the usual culprit. Trim or summarise history, and set a hard max-steps on any agent with tools so a looping agent fails fast instead of looping until the budget is gone.
• Never enable the Studio in production by default. Treat it as a local/staging tool. If you must expose it, put it on a separate domain or IP allowlist and audit access — the playground can invoke any registered agent with any prompt.
• Migrations on an existing database. Published Studio migrations add tables; review them before running against a database that already has data, and confirm index names don't collide with your own schema conventions.
• Version pinning. ^3.14 is the right constraint for this line. 3.14.2 carries no breaking changes, so patch updates are safe to take in a routine composer update; do read the compare diff for transitive dependency bumps, which is where most patch-level surprises hide.
• Debugging a bad run. Reach for the trace view first (message roles, tool inputs/outputs, token counts) before adding dump() calls. If the package ships a log channel, route agent logs to a dedicated channel so they don't drown your application log.
• Extension points worth knowing. Custom tools resolve through the Laravel container, so constructor-inject your services rather than reaching for facades inside a tool. Publishable views and config let you brand the UI without forking; prefer that over patching vendor/, which you'll lose on the next update.
• Watch the release cadence. With 3.14.x shipping frequently, keep the package and the underlying neuron-ai core in step — mismatched minor versions between the two is a known cause of confusing runtime errors, so upgrade them together rather than one at a time.