README

🪐 Atlas

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.

✨ Features

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)

🚀 Quick Start

composer require atlas-php/atlas

Supports Laravel 11+.

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

Define an Agent

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,
        ];
    }
}

Build a Tool

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';
    }
}

Chat with the Agent

$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

Speak with the Agent (Voice to Voice)

$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.

💡 Why Atlas?

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.

📖 Documentation

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

🧪 Sandbox

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.

🧹 Testing and Code Quality

Atlas uses several tools to maintain high code quality:

composer check

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

🤝 Contributing

We welcome contributions!

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

Please see our Contributing Guide for details.

📄 License

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

atlas-php / atlas

Maintainers

Package info

Statistics

Security