Laragents Laravel Package

Getting Started

• Install and pin deliberately. composer require edulazaro/laragents:^1.4, then publish the package's config (php artisan vendor:publish --provider="EduLazaro\Laragents\..." — grab the exact provider from php artisan vendor:publish output) and move any keys/endpoints into .env. Never commit the published config with secrets in it.
• Read the diff, not the release notes. The 1.4.0 notes are only a compare link (1.1.3...1.4.0), which means the jump from 1.1.3 skipped at least 1.2 and 1.3 without prose. Before adopting, open that compare URL and skim for renamed classes, changed method signatures, config key renames, and bumped minimum PHP/Laravel constraints in composer.json. That diff is your actual changelog.
• Where to look first, in order: the package's own tests/ directory (the most reliable spec for a thinly-documented package), the service provider (what it binds into the container and which extension points exist), the published config file (every tunable lives there), then the README quick start.
• First use case: wire a single agent to a single prompt, invoke it from a queued job rather than a controller, log the request/response pair, and assert on the result in a test using Http::fake(). Get that loop green before adding a second agent — it surfaces config, credential, and timeout issues cheaply.

Implementation Patterns

• Wrap it behind your own interface. Define an AgentRunner contract in your app and adapt the package behind it. On a package doing 1.1 → 1.4 minor releases, your app code should not reference package classes directly outside that one adapter.
• Agents as classes or config, never closures in controllers. One class/config block per agent (model, system prompt, tools, temperature, token caps). This keeps prompts diffable in review and lets you version them independently of application code.
• Always queue. Agent calls are network-bound and slow. Dispatch a job, set an explicit job timeout lower than the queue's retry_after, and implement failed() to record the error rather than silently dropping it. Use backoff for rate limits (429s) instead of tight retries.
• Persist every call. Store prompt, response, latency, token usage, and model in a table. You cannot control cost or debug behaviour without this, and it is the single highest-value addition you can make on day one.
• Test with fakes. Http::fake() around the transport layer works if the package uses the Laravel HTTP client; if it ships its own fake/assertion helpers, prefer those. Assert on your adapter's contract, not on the package's internals.
• Feature-flag per agent. A config-driven allowlist lets you roll out, disable, or swap a model in production without a deploy.
• Scope per tenant. If you are multi-tenant, resolve credentials and context through a tenancy-aware resolver rather than reading raw config at call time.

Gotchas and Tips

• Treat minor bumps as potentially breaking. 1.1.3 → 1.4.0 with no prose changelog is a signal, not a formality. Run composer update edulazaro/laragents --dry-run -W and read the diff before bumping, and keep the version constrained (^1.4) so a surprise 1.5 does not land in CI unpinned.
• Long calls vs. worker timeouts. An agent call can outlive retry_after, causing duplicate executions on retry. Set the job timeout explicitly and keep the queue's retry_after comfortably above it.
• Config caching bites. After changing .env, run php artisan config:clear (or config:cache in deploy scripts) — env edits appear to "do nothing" when a cached config is in play.
• Cost and latency blowups come from unbounded output. Cap max tokens and set an HTTP timeout in the published config; without a timeout, one hung request can pin a worker indefinitely.
• Redact before you log. API keys, and often PII in prompts and responses, end up in your persisted call log. Add a redaction step at write time rather than retrofitting it after an incident.
• Extension points to map early: container bindings in the service provider, publishable config/assets, any events emitted around a call (good hook for metrics), and macros/Macroable traits — these are your least invasive customisation surfaces if the package is otherwise closed.
• Debugging order when a call fails: (1) config:clear, (2) confirm credentials resolve from the expected source, (3) enable verbose HTTP logging at the client level, (4) check the package's own test suite for the current expected invocation shape — it moves faster than the docs.