Skip to main content

​
Installation

​
Requirements

  • PHP 8.2 or higher
  • Laravel 10.x, 11.x, or 12.x
  • A valid API key from a supported LLM provider (OpenAI, Anthropic, Google, etc.)

​
Install via Composer

composer require cognesy/instructor-laravel
# @doctest id="ba4e"
The package uses Laravel’s package auto-discovery mechanism, so the service provider and all four facades (StructuredOutput, Inference, Embeddings, AgentCtrl) are registered automatically. No manual registration is required for typical Laravel applications. Laravel config now separates native agent runtime settings from AgentCtrl code-agent settings:
  • config('instructor.agents') is reserved for native Cognesy\Agents
  • config('instructor.agent_ctrl') configures CLI code agents used by AgentCtrl
  • config('instructor.telemetry') owns Laravel telemetry wiring

​
Publish Configuration

Publish the configuration file to customize connections, extraction defaults, and other settings: 
php artisan vendor:publish --tag=instructor-config
# @doctest id="6bcf"
This creates config/instructor.php with all available options. The file ships with sensible defaults, so you can start using the package with just an API key and customize later as your needs grow.

​
Configure API Keys

Add your LLM provider API key to .env. You only need the key for the provider you intend to use: 
# OpenAI (default)
OPENAI_API_KEY=sk-...

# Or Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Or other providers
GEMINI_API_KEY=...
GROQ_API_KEY=...
MISTRAL_API_KEY=...
// @doctest id="7a60"
You can configure multiple providers simultaneously and switch between them at runtime using the connection() method on any facade.

​
Setup by Package

The Laravel package is the Laravel integration layer for four underlying packages. You do not install them separately in a Laravel app. Instead, you configure them through Laravel’s native config/instructor.php file and use the Laravel facades or container bindings. The standalone packages/config YAML loader is not responsible for reading config/instructor.php. Under Laravel, the service provider reads Laravel’s config repository directly and maps those values into the typed runtime config objects used by Instructor, Polyglot, and the HTTP client.
Underlying packageLaravel surfaceWhat to set upContinue with
packages/instructorStructuredOutput facade and Cognesy\Instructor\StructuredOutputConfigure your default LLM connection, extraction defaults, and response modelsFacades, Response Models, Configuration
packages/polyglotInference and Embeddings facades plus Cognesy\Polyglot\Inference\Inference and Cognesy\Polyglot\Embeddings\EmbeddingsConfigure inference connections in connections and embedding models in embeddings.connectionsFacades, Configuration, Events
packages/agentsNative Cognesy\Agents runtimeLaravel now reserves the agents config namespace for native agent runtime, persistence, and observability wiring. First-class container/runtime bindings are documented separately.Native Agents, Configuration
packages/agent-ctrlAgentCtrl facadeInstall the CLI agent you want to use, ensure its binary is available in PATH, then configure timeouts, working directory, and sandbox defaults in agent_ctrlCode Agents, Testing
packages/http-clientInternal Laravel-backed transportNo separate install is required; keep http.driver set to laravel to route requests through Laravel’s HTTP client and Http::fake()Configuration, Testing

​
packages/agents Under Laravel

Laravel keeps native agent runtime configuration under config/instructor.php in the agents section so it no longer collides with AgentCtrl. The Laravel package now ships the native runtime integration end to end:
  • agents.enabled
  • agents.session_store
  • agents.definitions
  • agents.tools
  • agents.capabilities
  • agents.schemas
  • agents.broadcasting
If you want database-backed native agent sessions: 
php artisan vendor:publish --tag=instructor-migrations
php artisan migrate
# @doctest id="abcb"
Then set: 
INSTRUCTOR_NATIVE_AGENT_SESSION_STORE=database
// @doctest id="42e3"
If you want Laravel broadcasting for native agent envelopes: 
INSTRUCTOR_NATIVE_AGENT_BROADCASTING_ENABLED=true
INSTRUCTOR_NATIVE_AGENT_BROADCAST_CONNECTION=reverb
// @doctest id="d1cf"
Telemetry is configured separately under config('instructor.telemetry').

​
packages/instructor Under Laravel

Structured output uses the default connection from config/instructor.php, then applies Laravel-specific extraction defaults such as output mode and retry behavior. In practice, setup means:
  • publish the config file
  • set at least one LLM API key
  • choose a default connection in connections
  • define extraction defaults in extraction
  • create response model classes and call StructuredOutput

​
packages/polyglot Under Laravel

Laravel exposes Polyglot through two entry points:
  • Inference for raw text, JSON, tool-calling, and streaming responses
  • Embeddings for vector generation
Both use the same published config file. Inference reads from connections; embeddings read from embeddings.connections. If you already configured providers for StructuredOutput, raw inference usually needs no additional setup.

​
packages/agent-ctrl Under Laravel

AgentCtrl does not use the LLM HTTP connections from config/instructor.php. It runs external agent CLIs from your Laravel application. Setup means:
  • install the agent CLI you want to use
  • make sure its executable is available in PATH
  • authenticate that CLI using its own provider workflow
  • set Laravel defaults for timeout, working directory, model, and sandbox in agent_ctrl

​
packages/http-client Under Laravel

Laravel already wires the HTTP client package into the container. All Instructor, Inference, and Embeddings calls use the Laravel-backed driver by default. Setup usually means only:
  • keep http.driver set to laravel
  • adjust http.timeout and http.connect_timeout if needed
  • use Http::fake() when you want transport-level HTTP tests

​
Verify Installation

Run the installation command to verify everything is configured correctly: 
php artisan instructor:install
# @doctest id="5dc7"
This will:
  1. Publish the configuration if not already published
  2. Check for API key configuration in your .env file
  3. Show next steps for getting started

​
Test Your Connection

Test that your API configuration is working by making a real API call: 
php artisan instructor:test
# @doctest id="f7e2"
This command displays your current configuration (connection name, driver, model, masked API key) and then performs a structured output extraction to confirm the full pipeline is operational. To test a specific connection: 
php artisan instructor:test --connection=anthropic
# @doctest id="76bd"
To test raw inference (without structured output extraction): 
php artisan instructor:test --inference
# @doctest id="9270"

​
Optional: Publish Stubs

If you want to customize the response model templates used by make:response-model: 
php artisan vendor:publish --tag=instructor-stubs
# @doctest id="90ee"
This publishes stubs to stubs/instructor/ in your application root. The command will prefer your custom stubs over the package defaults when generating new response models.

​
Manual Registration (Optional)

If you have disabled Laravel’s package auto-discovery, manually register the service provider. In Laravel 10, add it to config/app.php: 
'providers' => [
    // ...
    Cognesy\Instructor\Laravel\InstructorServiceProvider::class,
],

'aliases' => [
    // ...
    'StructuredOutput' => Cognesy\Instructor\Laravel\Facades\StructuredOutput::class,
    'Inference' => Cognesy\Instructor\Laravel\Facades\Inference::class,
    'Embeddings' => Cognesy\Instructor\Laravel\Facades\Embeddings::class,
    'AgentCtrl' => Cognesy\Instructor\Laravel\Facades\AgentCtrl::class,
],
// @doctest id="04d4"
In Laravel 11 and 12, register the provider in bootstrap/providers.php.

​
Upgrading

When upgrading to a new version, republish the configuration if there are new options: 
php artisan vendor:publish --tag=instructor-config --force
# @doctest id="4f2e"
Review the changelog for breaking changes before upgrading major versions.

​
Next Steps