README

Utopia Agents is a simple and lite library for building and managing AI agents in PHP applications. This library provides a collection of tools and utilities for creating, managing, and orchestrating AI agents with support for multiple AI providers. This library is maintained by the Appwrite team.

Although this library is part of the Utopia Framework project it is dependency free and can be used as standalone with any other PHP project or framework.

Getting Started

Install using composer:

composer require utopia-php/agents

System Requirements

Utopia Framework requires PHP 8.0 or later. We recommend using the latest PHP version whenever possible.

Features

Multiple AI Providers - Support for OpenAI, Anthropic, Deepseek, Perplexity, and XAI APIs
Flexible Message Types - Support for text and structured content in messages
Conversation Management - Easy-to-use conversation handling between agents and users
Model Selection - Choose from various AI models (GPT-4, Claude 3, Deepseek Chat, Sonar, Grok, etc.)
Parameter Control - Fine-tune model behavior with temperature and token controls

Usage

Basic Example

<?php

use Utopia\Agents\Agent;
use Utopia\Agents\Roles\User;
use Utopia\Agents\Messages\Text;
use Utopia\Agents\Conversation;
use Utopia\Agents\Adapters\OpenAI;

// Create an agent with OpenAI
$adapter = new OpenAI('your-api-key', OpenAI::MODEL_GPT_4_TURBO);
$agent = new Agent($adapter);

// Create a user
$user = new User('user-1', 'John');

// Start a conversation
$conversation = new Conversation($agent);
$conversation
    ->message($user, new Text('What is artificial intelligence?'))
    ->send();

Using Different AI Providers

OpenAI

use Utopia\Agents\Adapters\OpenAI;

$openai = new OpenAI(
    apiKey: 'your-api-key',
    model: OpenAI::MODEL_GPT_4_TURBO,
    maxTokens: 2048,
    temperature: 0.7
);

Available OpenAI Models:

MODEL_GPT_4_TURBO: Latest GPT-4 Turbo
MODEL_GPT_4: Standard GPT-4
MODEL_GPT_3_5_TURBO: Fast GPT-3.5 Turbo

Anthropic

use Utopia\Agents\Adapters\Anthropic;

$anthropic = new Anthropic(
    apiKey: 'your-api-key',
    model: Anthropic::MODEL_CLAUDE_3_SONNET,
    maxTokens: 2048,
    temperature: 0.7
);

Available Anthropic Models:

MODEL_CLAUDE_3_OPUS: Most powerful model
MODEL_CLAUDE_3_SONNET: Balanced performance
MODEL_CLAUDE_3_HAIKU: Fast and efficient
MODEL_CLAUDE_2_1: Previous generation

Deepseek

use Utopia\Agents\Adapters\Deepseek;

$deepseek = new Deepseek(
    apiKey: 'your-api-key',
    model: Deepseek::MODEL_DEEPSEEK_CHAT,
    maxTokens: 2048,
    temperature: 0.7
);

Available Deepseek Models:

MODEL_DEEPSEEK_CHAT: General-purpose chat model
MODEL_DEEPSEEK_CODER: Specialized for code-related tasks

Perplexity

use Utopia\Agents\Adapters\Perplexity;

$perplexity = new Perplexity(
    apiKey: 'your-api-key',
    model: Perplexity::MODEL_SONAR,
    maxTokens: 2048,
    temperature: 0.7
);

Available Perplexity Models:

MODEL_SONAR: General-purpose search model
MODEL_SONAR_PRO: Enhanced search model
MODEL_SONAR_DEEP_RESEARCH: Advanced search model
MODEL_SONAR_REASONING: Reasoning model
MODEL_SONAR_REASONING_PRO: Enhanced reasoning model

XAI

use Utopia\Agents\Adapters\XAI;

$xai = new XAI(
    apiKey: 'your-api-key',
    model: XAI::MODEL_GROK_2_LATEST,
    maxTokens: 2048,
    temperature: 0.7
);

Available XAI Models:

MODEL_GROK_2_LATEST: Latest Grok model
MODEL_GROK_2_IMAGE: Latest Grok model with image support

Managing Conversations

use Utopia\Agents\Roles\User;
use Utopia\Agents\Roles\Assistant;
use Utopia\Agents\Messages\Text;

// Create a conversation with system instructions
// Initialize roles
$user = new User('user-1'); 
$assistant = new Assistant('assistant-1');

$conversation = new Conversation($agent);
$conversation
    ->message($user, new Text('Hello!'))
    ->message($assistant, new Text('Hi! How can I help you today?'))
    ->message($user, new Text('What is the capital of France?'));

// Send and get response
$response = $conversation->send();

Working with Messages

use Utopia\Agents\Messages\Text;
use Utopia\Agents\Messages\Image;

// Text message
$textMessage = new Text('Hello, how are you?');

// Image message
$imageMessage = new Image($imageBinaryContent);
$mimeType = $imageMessage->getMimeType(); // Get the MIME type of the image

Configuring Agents

$agent = new Agent($adapter);
$agent
    ->setDescription('An AI agent specialized in research and analysis')
    ->setCapabilities(['research', 'analysis', 'writing']);

Tests

To run all unit tests, use the following Docker command:

docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests

To run static code analysis, use the following Psalm command:

docker compose exec tests vendor/bin/psalm --show-info=true

Security

We take security seriously. If you discover any security-related issues, please email security@appwrite.io instead of using the issue tracker.

Contributing

All code contributions - including those of people having commit access - must go through a pull request and be approved by a core developer before being merged. This is to ensure a proper review of all the code.

We truly ❤️ pull requests! If you wish to help, you can learn more about how you can contribute to this project in the contribution guide.

Copyright and license

The MIT License (MIT) http://www.opensource.org/licenses/mit-license.php

utopia-php / agents

Maintainers

Details