📚 Documentation

Atlas is a unified AI SDK for Laravel applications. It owns its own provider layer — no external AI package dependency. Atlas talks directly to AI provider APIs, manages the tool call loop, and provides optional persistence for conversations, execution tracking, and agent memory.

• Agents — Reusable classes encapsulating provider, model, instructions, tools, and behavior
• Tools — Typed tool classes with parameter schemas and dependency injection
• 10 Modalities — Text, images, audio (speech, music, sound effects), video, voice, embeddings, reranking
• Variable Interpolation — {variable} placeholders in instructions resolved at runtime
• Middleware — Four layers (agent, step, tool, provider) for logging, auth, metrics, and control
• Structured Output — Schema-validated JSON responses from any provider
• Streaming — SSE and Laravel Broadcasting with real-time chunk delivery
• Voice — Real-time bidirectional voice conversations with tool support
• Conversations — Multi-turn chat with message history, retry, and sibling tracking
• Persistence — Optional execution tracking and asset storage
• Queue Support — Async execution with broadcasting and callbacks
• Testing — Full fake system with assertions — no API keys required
• Provider Tools — Web search, code interpreter, file search via provider-native tools
• Provider Discovery — List available models, voices, and run content moderation
• Custom Providers — OpenAI-compatible endpoints or fully custom drivers
• All Providers — OpenAI, Anthropic, Google (Gemini), xAI (Grok), ElevenLabs, Cohere, Jina, plus any OpenAI-compatible API (Ollama, Groq, DeepSeek, Together, OpenRouter, LM Studio)

composer require atlas-php/atlas

Supports Laravel 11+.

php artisan vendor:publish --tag=atlas-config

use Atlasphp\Atlas\Agent;

class SupportAgent extends Agent
{
    public function provider(): ?string
    {
        return 'anthropic';
    }

    public function model(): ?string
    {
        return 'claude-sonnet-4-20250514';
    }

    public function instructions(): ?string
    {
        return <<<'PROMPT'
        You are a customer support specialist for {company_name}.

        ## Customer Context
        - **Name:** {customer_name}
        - **Account Tier:** {account_tier}

        ## Guidelines
        - Always greet the customer by name
        - For order inquiries, use `lookup_order` before providing details
        - Before processing refunds, verify eligibility using order data
        PROMPT;
    }

    public function tools(): array
    {
        return [
            LookupOrderTool::class,
            ProcessRefundTool::class,
        ];
    }
}

use Atlasphp\Atlas\Tools\Tool;
use Atlasphp\Atlas\Schema\Fields\StringField;

class LookupOrderTool extends Tool
{
    public function __construct(
        private OrderService $orders
    ) {}

    public function name(): string
    {
        return 'lookup_order';
    }

    public function description(): string
    {
        return 'Look up order details by order ID';
    }

    public function parameters(): array
    {
        return [
            new StringField('order_id', 'The order ID to look up'),
        ];
    }

    public function handle(array $args, array $context): mixed
    {
        $order = $this->orders->find($args['order_id']);

        return $order ? $order->toArray() : 'Order not found';
    }
}

$response = Atlas::agent('support')
    ->withVariables([
        'company_name' => 'Acme',
        'customer_name' => 'Sarah',
        'account_tier' => 'Premium',
    ])
    ->message('Where is my order #12345?')
    ->asText();

$response->text;    // "Hello Sarah! Let me look that up..."
$response->usage;   // Token usage
$response->steps;   // Tool call loop history

$session = Atlas::agent('support')
    ->withVariables([
        'company_name' => 'Acme',
        'customer_name' => 'Sarah',
        'account_tier' => 'Premium',
    ])
    ->asVoice();

return response()->json($session->toClientPayload());
// Returns ephemeral token + connection URL for WebRTC/WebSocket

See the Voice Integration Guide for full setup instructions.

The problem: Prompts scattered across controllers, duplicated configurations, business logic tightly coupled with AI calls, and no consistent way to add logging, validation, or error handling.

Atlas structures your AI layer:

• Agents — AI configurations live in dedicated classes, not inline across your codebase.
• Tools — Business logic stays in tool classes with typed parameters. Agents call tools; tools call your services.
• Middleware — Add logging, auth, or metrics at four execution layers without coupling the codebase.
• Testable — Full fake system with per-modality assertions using standard Laravel testing patterns.

atlasphp.org — Full guides, API reference, and examples.

• Getting Started — Installation and configuration
• Agents — Define reusable AI configurations
• Tools — Connect agents to your application
• Middleware — Extend with four middleware layers
• Modalities — Text, images, audio, video, voice, embeddings, and more
• Conversations — Multi-turn chat with persistence
• Voice — Real-time voice conversations
• Streaming — SSE and broadcasting
• Queue — Background execution
• Testing — Fakes and assertions

A fully functional chat interface demonstrating Atlas agents in action. Built with Vue 3, Tailwind CSS, and a Laravel JSON API.

See the Sandbox README for setup instructions and details.

Atlas uses several tools to maintain high code quality:

composer check

Tool	Purpose
Pest	Testing framework
Larastan	Static analysis
Laravel Pint	Code style
Codecov

We welcome contributions!

Support the community by giving a GitHub star. Thank you!

Please see our Contributing Guide for details.

Atlas is open-sourced software licensed under the MIT license.