Neuron Laravel Laravel Package

Getting Started

This release (2.0.0) is a compatibility release: the Laravel bridge now targets Neuron 4. The public surface of the Laravel package is largely unchanged, but the underlying agent framework had a major bump, so treat this as an upgrade task rather than a drop-in patch.

Minimal path:

1. composer require neuron-ai/neuron:^4.0 alongside the bridge package. Do not allow ^3 to remain in the lockfile — a mixed constraint will resolve to incompatible contracts and fail at runtime, not at install time.
2. Publish the config (php artisan vendor:publish, pick the neuron/bridge entry) and review the provider, model, and API-key settings. Prefer env() only inside the config file.
3. Set credentials in .env, then smoke-test with php artisan tinker: resolve the package's base agent from the container and run a trivial prompt. If that works, the wiring (service provider, HTTP client, config) is correct.
4. First real use case: a single agent class with one or two read-only tools — e.g. an "account assistant" that can query an Eloquent model and summarise results. Keep it synchronous behind a route or artisan command until you understand provider latency and token cost.

Look first at: the package's service provider (what it binds and publishes), the published config file, and the upstream Neuron 4 upgrade notes — the bridge is thin, so most breaking changes will come from the framework underneath.

Implementation Patterns

Agents as container-resolved classes. Define agents as classes with instructions and a tools() declaration, and resolve them via app()/injection rather than new. That lets tools receive their own dependencies (repositories, HTTP clients) and makes agents swappable in tests.

Keep tools thin. A tool should validate input, call a service or Eloquent query, and return a compact string/array. Business logic belongs in services; tool descriptions are prompt surface, so word them precisely — vague descriptions are the single biggest cause of wrong tool selection.

Queue long runs. Anything beyond a few seconds belongs in a job. Dispatch with a dedicated queue and a worker --timeout comfortably above your slowest provider call; the default 60s is frequently too low for tool-using agents.

Config-driven model selection. Read model/provider from config so tests and local dev can point at a cheap model or a fake. Bind provider clients in a service provider so swapping providers per environment is a config change, not a code change.

Observability. Hook the package/framework events (or a logging middleware) to record prompt, tool calls, token usage, and latency. Cost visibility is the thing teams most regret skipping.

Testing. Use the upstream test helpers to fake agent responses where available; otherwise Http::fake() the provider endpoint. Assert on tool invocations (spy the tool class) rather than on model prose, which is non-deterministic.

Orchestration. For multi-step work, prefer composing several small agents through a Laravel job/pipeline over one giant agent with ten tools. Persist conversation and intermediate state in the database; do not hold it in memory across queue hops.

Gotchas and Tips

• Major-version coupling. Neuron 4 means namespace and contract changes upstream. Existing agents written against Neuron 3 can boot fine and then fail mid-run with type errors. Run the full suite and one real end-to-end agent call before merging.
• Stale config cache. After upgrading, run php artisan config:clear (and optimize:clear on deploy). A cached config referencing an old provider class produces confusing "class not found" errors at boot.
• Restart workers. Long-lived queue workers keep pre-upgrade code in memory. Always php artisan queue:restart as part of the deploy.
• Duplicate provider registration. If an earlier version required manual registration in config/app.php, remove it — package discovery plus a manual entry yields double bindings and odd singleton behaviour.
• Timeouts stack multiplicatively. PHP max_execution_time, the queue worker --timeout, the queue retry_after, and the HTTP client timeout all apply. Order them: HTTP < worker < retry_after, or jobs get retried while still running and you pay twice.
• Tool exceptions become prompt content. Errors raised inside a tool are typically surfaced back to the model. Catch and sanitise them — raw stack traces and connection strings can leak into the transcript and into your logs.
• Streaming and buffering. With Octane, nginx proxying, or output buffering enabled, streamed tokens may arrive in one chunk. Disable buffering on the route or use an SSE response helper.
• env() outside config breaks under config:cache. A classic source of "works locally, null in production" API-key bugs.
• Cost runaway. Cap max tokens, set per-user rate limits with Laravel's RateLimiter, and add a hard iteration ceiling for tool loops — an agent that keeps calling a failing tool will happily spend money in a loop.
• Extension points worth knowing: the publishable config, container bindings for provider/HTTP clients, the tool contract for custom tools, and framework events for usage/observability. These are where you customise without forking.
• Debugging recipe: log the raw request/response payload (redacting secrets), dump the message history on failure, and reproduce outside the queue in tinker — queue serialisation masks the real exception more often than not.