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 package	Laravel surface	What to set up	Continue with
`packages/instructor`	`StructuredOutput` facade and `Cognesy\Instructor\StructuredOutput`	Configure your default LLM connection, extraction defaults, and response models	Facades, Response Models, Configuration
`packages/polyglot`	`Inference` and `Embeddings` facades plus `Cognesy\Polyglot\Inference\Inference` and `Cognesy\Polyglot\Embeddings\Embeddings`	Configure inference connections in `connections` and embedding models in `embeddings.connections`	Facades, Configuration, Events
`packages/agents`	Native `Cognesy\Agents` runtime	Laravel 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-ctrl`	`AgentCtrl` facade	Install the CLI agent you want to use, ensure its binary is available in `PATH`, then configure timeouts, working directory, and sandbox defaults in `agent_ctrl`	Code Agents, Testing
`packages/http-client`	Internal Laravel-backed transport	No 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:

Publish the configuration if not already published
Check for API key configuration in your .env file
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

Configuration — Configure connections and settings
Facades — Learn how to use the facades
Response Models — Create your first response model

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Installation

Installation

Requirements

Install via Composer

Publish Configuration

Configure API Keys

Setup by Package

`packages/agents` Under Laravel

`packages/instructor` Under Laravel

`packages/polyglot` Under Laravel

`packages/agent-ctrl` Under Laravel

`packages/http-client` Under Laravel

Verify Installation

Test Your Connection

Optional: Publish Stubs

Manual Registration (Optional)

Upgrading

Next Steps

​Installation

​Requirements

​Install via Composer

​Publish Configuration

​Configure API Keys

​Setup by Package

​packages/agents Under Laravel

​packages/instructor Under Laravel

​packages/polyglot Under Laravel

​packages/agent-ctrl Under Laravel

​packages/http-client Under Laravel

​Verify Installation

​Test Your Connection

​Optional: Publish Stubs

​Manual Registration (Optional)

​Upgrading

​Next Steps

Installation

Requirements

Install via Composer

Publish Configuration

Configure API Keys

Setup by Package

`packages/agents` Under Laravel

`packages/instructor` Under Laravel

`packages/polyglot` Under Laravel

`packages/agent-ctrl` Under Laravel

`packages/http-client` Under Laravel

Verify Installation

Test Your Connection

Optional: Publish Stubs

Manual Registration (Optional)

Upgrading

Next Steps