📚 Official Documentation | 🚀 See Examples (31)

🪐 Atlas

Atlas is a Laravel package for orchestrating AI agents, tools, and execution pipelines. It provides structure and best practices for building maintainable, testable AI features at the application level.

Built on Prism PHP, Atlas stays intentionally lightweight by focusing on application-level concerns such as agent definitions, tool orchestration, prompt templates, and execution pipelines. Prism is responsible for all LLM communication and provider APIs.

✨ Features

• Agents – Define your AI agent behavior and configurations
• Tools – Connect agents to your services with validated parameters and structured results
• MCP Tools – Integrate external tools from MCP servers via Prism Relay
• Dynamic Prompts – Inject context {variables} into system prompts at runtime for personalized interactions
• Pipelines – Add logging, auth, rate limiting, or metrics without coupling the codebase
• Full Prism Access – Use embeddings, images, speech, moderation, and structured output without limits
• All Providers: Anthropic, OpenAI, Gemini, Mistral, Ollama, Groq, DeepSeek, xAI, OpenRouter, ElevenLabs (audio), VoyageAI (embeddings), Local LLMs, and Custom LLMs

Quick Start

composer require atlas-php/atlas

# Publish Atlas configuration
php artisan vendor:publish --tag=atlas-config

# Publish Prism configuration (if not already published)
php artisan vendor:publish --tag=prism-config

Define an Agent

use Atlasphp\Atlas\Agents\AgentDefinition;

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

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

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

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

        ## Available Tools
        - **lookup_order** - Retrieve order details by order ID
        - **process_refund** - Process refunds for eligible orders

        ## 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, 
            RefundTool::class
        ];
    }
}

Build a Tool

use Atlasphp\Atlas\Tools\ToolDefinition;
use Atlasphp\Atlas\Tools\Support\ToolContext;
use Atlasphp\Atlas\Tools\Support\ToolParameter;
use Atlasphp\Atlas\Tools\Support\ToolResult;

class LookupOrderTool extends ToolDefinition
{
    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 [
            ToolParameter::string('order_id', 'The order ID to look up', required: true),
        ];
    }

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

        if (! $order) {
            return ToolResult::error('Order not found');
        }

        return ToolResult::json($order->toArray());
    }
}

Chat with the Agent

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

echo $response->text();
// $response->usage();
// Hello Sarah, your order is out for delivery. Anything else I can help with?

Why Atlas?

The problem: Prompts scattered across controllers, duplicated configurations, businesses logic tightly coupled with tools, and no consistent way to add logging, validation or even proper error handling.

Atlas decouples your businesses logic:

• 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.
• Pipelines - Add logging, auth, or metrics to all Prism/Atlas operations without coupling the codebase.
• Testable - Mock agents and fake tool responses with standard Laravel testing patterns.

Atlas doesn't replace Prism. It organizes how you use Prism in real applications.

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
• MCP Integration - External tools from MCP servers
• Pipelines - Extend with middleware

🚀 Examples

Agents — Reusable AI configurations for different roles and tasks.

• Customer Support
• Sales Support
• Customer Service
• Code Review
• Content Writer
• Data Analyst
• HR Assistant
• IT Helpdesk (MCP)
• Orchestrator

Tools — Connect agents to your application logic and external services.

• Order Lookup
• Knowledge Base Search
• Create Ticket
• Send Notification
• Database Query
• Agent Delegation

Pipelines — Middleware for logging, auth, caching, and error handling.

• Audit Logging
• Authentication
• Rate Limiting
• Token Usage
• Cache Embeddings
• Error Recovery

Capabilities — Streaming, structured output, vision, audio, and more.

• Streaming
• Structured Output
• Multi-Turn Chat
• Semantic Search
• RAG
• Vision
• Text-to-Speech
• Speech-to-Text
• Content Moderation
• Image Generation

💬 Sandbox - Atlas Chat Example

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.