Weave Code
Agents Laravel Package
packstub/agents
packstub/agents is a Laravel package that provides a clean, extensible foundation for defining and running AI agents, with support for tools, prompts, and workflows that integrate smoothly into your application.
AI agents for Laravel: an agent engine and an MCP server sharing one tool list, built on laravel/ai and laravel/mcp. The engine behind Filament Agents; runs without Filament.
Frequently asked questions about Agents
- How do I install packstub/agents in a Laravel application?
- Install it with Composer using composer require packstub/agents. It is a standard Laravel package, so its service provider and configuration are registered and published following normal Laravel conventions, and Composer resolves its laravel/ai and laravel/mcp dependencies. Check the package composer.json for the exact Laravel version constraints your application must satisfy.
- How do I define an AI agent and its tools with packstub/agents?
- The package provides an agent engine and an MCP server that share one tool list, so tools you expose over MCP are the same tools the agent can call. You define agents with their tools, prompts, and workflows using the package's extensible foundation, then run turns through the engine or the agents:run Artisan entry point. This keeps tool definitions consistent whether the caller is an internal agent turn or an MCP client.
- How do I configure the decision classifier driver in packstub/agents?
- Set AGENT_DECISION_CLASSIFIER_DRIVER to choose how free-text decisions are read. The built-in modes are agent, which uses the agent itself, jev, which sends questions to TypeSafe, or an application-owned class bound to the DecisionClassifier contract. The default path is unchanged, so existing deployments inherit nothing new unless they opt in.
- Can I use a custom DecisionClassifier instead of sending proposal text to TypeSafe?
- Yes. Packstub\Agents\Contracts\DecisionClassifier is a container-resolvable extension point, so you can implement the interface in your application, bind it in a service provider, and select it through AGENT_DECISION_CLASSIFIER_DRIVER. This is the intended escape hatch for teams that cannot send proposal text or user replies to a third party, and it should be treated as an explicit product decision rather than a fallback.
- What data does the jev decision classifier send to TypeSafe?
- With the jev driver, the typed reply and the proposal questions are sent to TypeSafe for classification. That makes TYPESAFE_API_KEY a production dependency and adds roughly 100 ms of latency per choice question, with one question per proposal. Teams should complete a security and privacy review, confirm retention and DPA terms, and decide whether that egress is acceptable before enabling jev.
- What does AGENT_DECISION_CLASSIFIER_MIN_CONFIDENCE control?
- It sets a confidence floor for classifiers that report confidence, and it defaults to 0.8. Drivers that emit no confidence, such as the agent driver, are exempt from the floor, so identical replies can be treated differently depending on which driver is active. Teams adopting jev inherit a threshold they did not choose, so review and tune it for your domain.
- How can I monitor and tune decision classifier confidence in packstub/agents?
- AgentTurn exposes decisionDriver() and decisionConfidence(), which tell you which classifier read each reply and how sure it was. You can feed those values into your product telemetry and use them to tune AGENT_DECISION_CLASSIFIER_MIN_CONFIDENCE after launch instead of guessing. That observability is what makes the confidence floor a measurable setting rather than a fixed assumption.
- Do agent decisions run synchronously or on a queue worker in packstub/agents?
- In v1.10.0, typed decisions run synchronously in the originating request through AgentRun, Artisan commands, or the email channel. A click in chat still dispatches to the worker, so a single decision flow can occupy two execution contexts. That is a correctness fix, but it is important to test both paths if your integration assumes decisions always resolve on a queue worker.
- Does packstub/agents require Filament?
- No. packstub/agents is the engine behind Filament Agents, but it runs without Filament and can be used in any Laravel application. It adds an application-level agent runtime with turn orchestration, tool proposals, human decision capture, chat surfaces, an email channel, and tenant scoping. Filament is only relevant if you want the Filament-based UI layer.
- What happens if TypeSafe is unavailable or TYPESAFE_API_KEY is missing?
- A failed classification degrades to treating the reply as a question, which is safe but user-visible. v1.10.0 does not state a circuit breaker or a local fallback to the agent driver on TypeSafe outage, so plan alerting for missing or rotated keys and degraded API responses. You should decide explicitly whether a loud failure or silent conversion of decisions into questions fits your operations.
Weaver
How can I help you explore Laravel packages today?