Chat

Execute conversations with AI agents using the Atlas chat API. Atlas doesn't store conversation history—your application manages persistence and passes history on each request.

Prism Reference

Atlas automatically builds messages into Prism's format. For detailed text generation documentation including message chains, see Prism Text Generation.

Basic Chat

php

use Atlasphp\Atlas\Atlas;

$response = Atlas::agent('support-agent')->chat('Hello, I need help with my order');

echo $response->text;
// "Hi! I'd be happy to help with your order. Could you provide your order number?"

Chat with History

Pass conversation history for context:

php

$response = Atlas::agent('support-agent')
    ->withMessages($messages)
    ->chat('Where is my package?');

Message Format

Messages can be provided in two formats: array format for persistence/serialization, or Prism message objects for full Prism compatibility.

Array Format

Ideal for storing in databases and JSON serialization:

php

$messages = [
    ['role' => 'user', 'content' => 'Hello!'],
    ['role' => 'assistant', 'content' => 'Hi there! How can I help?'],
    ['role' => 'user', 'content' => 'I have a question about my order'],
];

Prism Message Objects

For direct Prism compatibility and full API access:

php

use Prism\Prism\ValueObjects\Messages\UserMessage;
use Prism\Prism\ValueObjects\Messages\AssistantMessage;
use Prism\Prism\ValueObjects\Messages\SystemMessage;

$messages = [
    new SystemMessage('You are a helpful assistant.'),
    new UserMessage('Hello!'),
    new AssistantMessage('Hi there! How can I help?'),
];

$response = Atlas::agent('support-agent')
    ->withMessages($messages)
    ->chat('I have a question');

Role/Class	Description
`user` / `UserMessage`	Messages from the user
`assistant` / `AssistantMessage`	Responses from the AI
`system` / `SystemMessage`	System instructions

Attachments

Add images, documents, audio, and video to chat requests for vision analysis and document processing. Atlas uses Prism media objects directly for a consistent API.

Prism Reference

For detailed input modalities documentation, see Prism's Images, Documents, Audio, and Video guides.

Basic Attachments

Pass Prism media objects as the second argument to chat():

php

use Atlasphp\Atlas\Atlas;
use Prism\Prism\ValueObjects\Media\Image;
use Prism\Prism\ValueObjects\Media\Document;
use Prism\Prism\ValueObjects\Media\Audio;
use Prism\Prism\ValueObjects\Media\Video;

// Image from URL
$response = Atlas::agent('vision-agent')
    ->chat('What do you see in this image?', [
        Image::fromUrl('https://example.com/photo.jpg'),
    ]);

// Document
$response = Atlas::agent('analyzer')
    ->chat('Summarize this document', [
        Document::fromUrl('https://example.com/report.pdf'),
    ]);

// Audio
$response = Atlas::agent('transcriber')
    ->chat('What is being said?', [
        Audio::fromUrl('https://example.com/speech.mp3'),
    ]);

// Video
$response = Atlas::agent('analyzer')
    ->chat('Describe what happens', [
        Video::fromUrl('https://example.com/clip.mp4'),
    ]);

Source Types

Prism media objects support multiple source types:

php

use Prism\Prism\ValueObjects\Media\Image;

// From URL
Image::fromUrl('https://example.com/image.jpg')

// From local file path
Image::fromLocalPath('/path/to/image.png')

// From base64 data
Image::fromBase64($base64Data, 'image/png')

// From Laravel Storage
Image::fromStoragePath('images/photo.png', 'image/png', 's3')

// From provider file ID
Image::fromFileId('file-abc123')

The same methods are available on Document, Audio, and Video classes.

Multiple Attachments

php

use Prism\Prism\ValueObjects\Media\Image;
use Prism\Prism\ValueObjects\Media\Document;

// Multiple images
$response = Atlas::agent('vision')
    ->chat('Compare these images', [
        Image::fromUrl('https://example.com/before.jpg'),
        Image::fromUrl('https://example.com/after.jpg'),
    ]);

// Different media types
$response = Atlas::agent('analyzer')
    ->chat('Explain the chart using the document data', [
        Image::fromUrl('https://example.com/chart.png'),
        Document::fromUrl('https://example.com/data.pdf'),
    ]);

Builder Style

For cases where you need to configure attachments separately, use withMedia():

php

use Prism\Prism\ValueObjects\Media\Image;

$response = Atlas::agent('vision')
    ->withMedia([
        Image::fromUrl('https://example.com/photo.jpg'),
    ])
    ->chat('Describe this image');

// Both styles can be combined (attachments are merged)
$response = Atlas::agent('vision')
    ->withMedia([Image::fromUrl('https://example.com/photo1.jpg')])
    ->chat('Compare with this', [
        Image::fromUrl('https://example.com/photo2.jpg'),
    ]);

Provider Support

Not all providers support all media types. Check your provider's documentation for supported modalities.

Multi-Turn Conversations

Use the fluent builder to configure all context:

php

$response = Atlas::agent('support-agent')
    ->withMessages($messages)
    ->withVariables([
        'user_name' => 'Alice',
        'account_tier' => 'premium',
    ])
    ->withMetadata([
        'user_id' => 123,
        'session_id' => 'abc-456',
    ])
    ->chat('Check my recent orders');

Configuration Methods

Method	Description
`withMessages(array $messages)`	Conversation history (array format or Prism message objects)
`withVariables(array $variables)`	Variables for system prompt interpolation
`withMetadata(array $metadata)`	Metadata for pipeline middleware and tools
`withProvider(string $provider, ?string $model)`	Override agent's provider/model
`withSchema(Schema $schema)`	Schema for structured output (details)
`withMedia(array $media)`	Attach Prism media objects via builder pattern

All Prism methods are available via pass-through (e.g., withToolChoice(), withMaxTokens()).

Prism Passthrough Methods

Atlas provides full access to all Prism methods through passthrough. Any method available on Prism's generator can be called directly on the Atlas agent builder:

php

use Prism\Prism\Enums\ToolChoice;

$response = Atlas::agent('support-agent')
    ->withToolChoice(ToolChoice::Any)      // Force tool usage
    ->withClientRetry(3, 100)              // Retry with backoff
    ->usingTopP(0.9)                       // Top-p sampling
    ->withMaxTokens(2000)                  // Limit response length
    ->chat('Help me find my order');

Common Passthrough Methods

Method	Description
`withToolChoice(ToolChoice $choice)`	Control how tools are selected (`Auto`, `Any`, `None`)
`withClientRetry(int $times, int $sleepMs)`	Automatic retries with backoff
`usingTopP(float $topP)`	Top-p (nucleus) sampling
`usingTopK(int $topK)`	Top-k sampling
`withMaxTokens(int $tokens)`	Maximum response tokens
`withClientOptions(array $options)`	HTTP client configuration
`withProviderOptions(array $options)`	Provider-specific options

See Prism Text Generation for the complete API.

Response Handling

Chat operations return Prism's response object directly:

php

// Text response
echo $response->text;

// Token usage
echo $response->usage->promptTokens;
echo $response->usage->completionTokens;

// Check for content
if ($response->text !== null) {
    // Handle text response
}

See Prism Response for the complete response API.

Next Steps

Streaming — Real-time streaming responses
Structured — Schema-based responses

Chat ​

Basic Chat ​

Chat with History ​

Message Format ​

Array Format ​

Prism Message Objects ​

Attachments ​

Basic Attachments ​

Source Types ​

Multiple Attachments ​

Builder Style ​

Multi-Turn Conversations ​

Configuration Methods ​

Prism Passthrough Methods ​

Common Passthrough Methods ​

Response Handling ​

Next Steps ​