Configuration#

php artisan packstub-agents:install publishes config/packstub-agents.php. Most values can also be set fluently on AgentsPlugin in the panel provider; the plugin mirrors those into the config so every runtime (queue, console, MCP requests) sees one truth.

config/packstub-agents.php#

The provider keys themselves live in laravel/ai's config/ai.php (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY, and so on for the other providers).

models#

'models' => [
    'anthropic' => [
        'auto' => ['label' => null, 'model' => env('AGENT_MODEL', 'claude-opus-5'), 'effort' => 'medium'],
        'fast' => ['label' => null, 'model' => env('AGENT_MODEL_FAST', 'claude-haiku-4-5'), 'effort' => null],
        'deep' => ['label' => null, 'model' => env('AGENT_MODEL_DEEP', 'claude-opus-5'), 'effort' => 'xhigh'],
        // 'flash' => ['label' => 'Gemini Flash', 'provider' => 'gemini', 'model' => 'gemini-3.5-flash-lite', 'effort' => 'low'],
        // 'local' => ['label' => 'Local', 'provider' => 'ollama', 'model' => 'llama3.3', 'effort' => null, 'failover' => []],
    ],
    'openai' => [
        'auto' => ['label' => null, 'model' => env('AGENT_MODEL'), 'effort' => 'medium'],
        'fast' => ['label' => null, 'model' => env('AGENT_MODEL_FAST'), 'effort' => 'low'],
        'deep' => ['label' => null, 'model' => env('AGENT_MODEL_DEEP'), 'effort' => 'high'],
    ],
    'gemini' => [
        'auto' => ['label' => null, 'model' => env('AGENT_MODEL', 'gemini-3.8-flash'), 'effort' => 'medium'],
        'fast' => ['label' => null, 'model' => env('AGENT_MODEL_FAST', 'gemini-3.5-flash-lite'), 'effort' => 'low'],
        'deep' => ['label' => null, 'model' => env('AGENT_MODEL_DEEP', 'gemini-3.8-flash'), 'effort' => 'high'],
    ],
    'xai' => [
        'auto' => ['label' => null, 'model' => env('AGENT_MODEL', 'grok-4.6'), 'effort' => 'medium'],
        'fast' => ['label' => null, 'model' => env('AGENT_MODEL_FAST', 'grok-4.6'), 'effort' => 'low'],
        'deep' => ['label' => null, 'model' => env('AGENT_MODEL_DEEP', 'grok-4.6'), 'effort' => 'xhigh'],
    ],
],

Each entry is one item in the picker. Its fields:

The picker shows the list of the provider in use: models[provider], or the workspace's own provider when it brings a key. Rename, remove or add entries; the keys are yours.

A provider without entries#

Ollama, OpenRouter, Mistral, Groq, DeepSeek… get two entries: auto on the provider's smartest model and fast on its cheapest, as laravel/ai names them, with no effort. On OpenRouter those are Claude Opus 5 and Claude Haiku 4.5, routed through OpenRouter. To run the models you chose the provider for, add its list, with an OpenRouter model id (vendor/model, from openrouter.ai/models) in each entry:

'models' => [
    'openrouter' => [
        'auto' => ['label' => 'Mercury 2.5', 'model' => 'inception/mercury-2.5', 'effort' => null],
        'fast' => ['label' => 'GLM 5.3 Flash', 'model' => 'z-ai/glm-5.3-flash', 'effort' => null],
        'deep' => ['label' => 'DeepSeek 4.1 Flash', 'model' => 'deepseek/deepseek-v4.1-flash', 'effort' => null],
    ],
],

The key is OPENROUTER_API_KEY in .env, read by the openrouter entry of laravel/ai's config/ai.php; that entry also takes a url for a compatible gateway and the http_referer and x_title headers OpenRouter uses for app attribution. Effort stays null on OpenRouter, since the reasoning knob differs per model behind it.

Mixing providers#

One list can offer models of several providers. An entry names the provider it runs on with provider; its model and effort are in that provider's terms. Claude as the default, Gemini Flash for cheap questions and a local Ollama model for data that must not leave the server:

'provider' => 'anthropic',
'failover' => ['gemini'],

'models' => [
    'anthropic' => [
        'auto' => ['label' => null, 'model' => 'claude-opus-5', 'effort' => 'medium'],
        'fast' => ['label' => null, 'model' => 'claude-haiku-4-5', 'effort' => null],
        'flash' => ['label' => 'Gemini Flash', 'provider' => 'gemini', 'model' => 'gemini-3.5-flash-lite', 'effort' => 'low'],
        'local' => ['label' => 'Local', 'provider' => 'ollama', 'model' => 'llama3.3', 'effort' => null, 'failover' => []],
    ],
],

ANTHROPIC_API_KEY=sk-ant-…
GEMINI_API_KEY=AIza…
OLLAMA_API_KEY=local

• The entries live under the platform provider's list (anthropic here); AGENT_PROVIDER picks the list, provider on an entry picks where that entry runs.
• An entry on another provider is listed only when that provider has a key in config/ai.php. Without GEMINI_API_KEY, Gemini Flash is left out, quietly. Ollama needs no key, so give OLLAMA_API_KEY any value for its entry to count as configured.
• The picker groups the entries under provider headings, the platform provider first: Anthropic, then Gemini, then Ollama.
• Failover works per entry: the global failover list applies to every entry, with the entry's own provider skipped and the platform provider included when it is listed. Here Claude falls back to Gemini, and Gemini Flash has nothing to fall back to. An entry's own failover replaces the global list; [] on local keeps that model local.
• A workspace on its own key sees only the entries of its provider, see Tenancy. The chat is on when the provider in use has a key, or when any listed entry's provider has one.

AgentsPlugin#

use Packstub\Agents\AgentsPlugin;

AgentsPlugin::make()
    ->name('Ask Acme')
    ->agent(Assistant::class)
    ->server(AcmeServer::class)
    ->tools([SearchOrders::class, ShowTable::class])
    ->resources([OrderResource::class, CustomerResource::class])
    ->middleware([AuditTurns::class])
    ->authorizeUsing(fn (string $ability): bool => auth()->user()->can($ability))
    ->roleLabelUsing(fn (): ?string => auth()->user()->role?->getLabel())
    ->credentialsUsing(fn (): ?WorkspaceCredentials => ...)
    ->chat(true, driver: 'queue')
    ->agentAccess(enabled: true, ability: 'setup.view', group: 'Setup')
    ->limits(enabled: true, authorize: fn (): bool => auth()->user()->is_admin)
    ->turnLog()
    ->slideOver()
    ->shortcut('mod+j')
    ->hideAskButtonOn(['*.pages.dashboard'])
    ->embeddedTable(limit: 25)
    ->promptGuard()
    ->redact(patterns: ['iban' => '/\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{4}){3,7}\b/'])
    ->classify(topics: ['orders', 'stock', 'billing', 'how-to'])
    ->webSearch(allow: ['docs.acme.com', 'laravel.com'], max: 3)
    ->knowledgeBase(Article::class, 'embedding', content: 'body', url: fn (Article $a) => route('help.show', $a));

Two panels may register the plugin: the tenant panel with the chat and the token page, the operator panel with chat(false)->agentAccess(false)->limits(). The plugin's id is packstub-agents ($panel->getPlugin('packstub-agents')).

The Agents facade#

Packstub\Agents\Facades\Agents reads back what the app told the package: name(), tenant(), inPanel(), toolClasses(), resourceClasses(), middleware(), allows($ability), roleLabel(), credentials(), canManageLimits(), registeredResources(), optInTools(), knowledge(), redactor(), agentAccess(), agentAccessAbility(), agentAccessGroup(), askButtonHiddenOn($routeName), the tenancy hooks (tenantModelClass(), tenantSlugAttribute(), tenantResolver(), tenantEnterHook()), and context() — the AgentContext that knows who is acting and where (the panel's FilamentContext, whose panel() is the panel the assistant lives in, or the LaravelContext of a plain app). Tools and views use it; your own code may too. Without a panel the same facade is how the app registers itself — useAgent(), useServer(), useTools(), addTools(), useResources(), useMiddleware(), authorizeUsing(), roleLabelUsing(), credentialsUsing(), limitsAuthorizeUsing(), tenantUsing(), tenantModel(), enteringTenant(), knowledgeBase(), redactUsing() — see Agents for Laravel.

Translations and views#

Strings are __() calls keyed by the English text, with JSON files for German, Spanish, Romanian and Russian in resources/lang. Add your own language by publishing a JSON file with the same keys into your app's lang/ directory. Views are published with vendor:publish --tag=packstub-agents-views and live under the packstub-agents:: namespace.