Laravel AI SDK 正式发布

Agent：核心交互单元

SDK 的核心概念是 Agent。每个 Agent 是一个 PHP 类，封装了系统指令、对话上下文、工具和输出格式。可以把它理解为一个专用助手------销售教练、文档分析器、客服机器人------配置一次，随处调用。

通过 Artisan 命令创建：

复制代码

php artisan make:agent SalesCoach

生成的类实现 Agent 接口，定义 instructions() 方法提供系统提示词，然后调用 prompt() 发起对话：

复制代码

$response = SalesCoach::make(user: $user)
    ->prompt('分析这段销售录音...');

return (string) $response;

prompt() 方法支持在调用时切换服务商和模型：

复制代码

$response = (new SalesCoach)->prompt(
    '分析这段销售录音...',
    provider: 'anthropic',
    model: 'claude-haiku-4-5-20251001',
    timeout: 120,
);

如果不想创建专门的类，也可以用匿名 Agent 快速调用：

复制代码

use function Laravel\Ai\{agent};

$response = agent(
    instructions: 'You are an expert at software development.',
)->prompt('Tell me about Laravel');

结构化输出

Agent 可以返回结构化数据，而不仅仅是纯文本。实现 HasStructuredOutput 接口，定义 schema() 方法即可：

复制代码

public function schema(JsonSchema $schema): array
{
    return [
        'feedback' => $schema->string()->required(),
        'score' => $schema->integer()->min(1)->max(10)->required(),
    ];
}

调用后直接当数组用：

复制代码

$response = (new SalesCoach)->prompt('分析这段录音...');

return $response['score']; // 8

对话记忆

Agent 支持自动持久化对话历史。使用 RemembersConversations trait 后，SDK 会自动将对话存入数据库，后续可以通过 continue() 方法继续之前的对话：

复制代码

// 开始新对话
$response = (new SalesCoach)->forUser($user)->prompt('你好！');
$conversationId = $response->conversationId;

// 继续对话
$response = (new SalesCoach)
    ->continue($conversationId, as: $user)
    ->prompt('接着刚才的话题...');

工具系统

Agent 可以使用工具来扩展能力。通过 make:tool 命令创建工具类，定义输入 schema 和 handle() 方法：

复制代码

class RandomNumberGenerator implements Tool
{
    public function description(): string
    {
        return '生成加密安全的随机数。';
    }

    public function handle(Request $request): string
    {
        return (string) random_int($request['min'], $request['max']);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'min' => $schema->integer()->min(0)->required(),
            'max' => $schema->integer()->required(),
        ];
    }
}

SDK 还内置了几个服务商级别的工具：

WebSearch --- 让 Agent 搜索网页，支持 Anthropic、OpenAI、Gemini
WebFetch --- 让 Agent 抓取网页内容，支持 Anthropic、Gemini
FileSearch --- 在向量存储中搜索文件，支持 OpenAI、Gemini
SimilaritySearch --- 基于 Eloquent 模型的向量相似度搜索，用于 RAG 场景

流式响应与广播

对于需要实时输出的场景，Agent 支持流式响应。返回值可以直接作为路由响应，自动发送 SSE：

复制代码

Route::get('/coach', function () {
    return (new SalesCoach)->stream('分析这段录音...');
});

流式事件还可以通过 Laravel Broadcasting 广播到前端频道，或者使用 Vercel AI SDK 协议与前端框架对接：

复制代码

return (new SalesCoach)
    ->stream('分析这段录音...')
    ->usingVercelDataProtocol();

队列处理

耗时的 AI 请求可以推入队列在后台处理：

复制代码

(new SalesCoach)
    ->queue($request->input('transcript'))
    ->then(function (AgentResponse $response) {
        // 处理响应...
    })
    ->catch(function (Throwable $e) {
        // 处理异常...
    });

图像生成

Image 类提供了简洁的图像生成接口，支持 OpenAI、Gemini 和 xAI：

复制代码

use Laravel\Ai\Image;

$image = Image::of('厨房台面上的甜甜圈')
    ->quality('high')
    ->landscape()
    ->generate();

$path = $image->store();

支持附加参考图像进行风格迁移，也可以推入队列异步生成。

音频与转录

语音合成（TTS）和语音转录（STT）同样被纳入 SDK：

复制代码

use Laravel\Ai\Audio;
use Laravel\Ai\Transcription;

// 文字转语音
$audio = Audio::of('I love coding with Laravel.')
    ->female()
    ->instructions('用海盗的语气说')
    ->generate();

// 语音转文字
$transcript = Transcription::fromStorage('audio.mp3')
    ->diarize() // 按说话人分段
    ->generate();

TTS 支持 OpenAI 和 ElevenLabs，STT 同样支持这两个服务商。

Embeddings 与向量搜索

生成向量嵌入变得非常直观。Laravel 的 Stringable 类新增了 toEmbeddings() 方法：

复制代码

$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings();

配合 PostgreSQL 的 pgvector 扩展，可以在数据库中直接进行向量相似度查询：

复制代码

$documents = Document::query()
    ->whereVectorSimilarTo('embedding', '纳帕谷最好的酒庄')
    ->limit(10)
    ->get();

传入字符串时，Laravel 会自动生成嵌入向量再进行查询，不需要手动处理。Embedding 还支持缓存，避免重复调用 API。

Reranking

Reranking 可以对搜索结果按语义相关性重新排序，支持 Cohere 和 Jina：

复制代码

$posts = Post::all()->rerank('body', 'Laravel 教程');

这个功能直接以 Collection 宏的形式提供，可以对 Eloquent 集合按指定字段做语义重排。

文件与向量存储

SDK 提供了文件管理和向量存储的完整方案。文件可以上传到服务商存储后反复引用，向量存储则用于 RAG 场景下的文件检索：

复制代码

use Laravel\Ai\Files\Document;
use Laravel\Ai\Stores;

// 上传文件
$stored = Document::fromPath('/path/to/report.pdf')->put();

// 创建向量存储并添加文件
$store = Stores::create('知识库');
$store->add($stored);

Failover

调用时传入服务商数组，SDK 会在主服务商不可用时自动切换到备用服务商：

复制代码

$response = (new SalesCoach)->prompt(
    '分析这段录音...',
    provider: ['openai', 'anthropic'],
);

Agent 配置

Agent 支持通过 PHP Attribute 配置参数，包括最大步数、最大 token 数、温度、超时时间等：

复制代码

#[MaxSteps(10)]
#[MaxTokens(4096)]
#[Provider('anthropic')]
#[Temperature(0.7)]
#[Timeout(120)]
class SalesCoach implements Agent
{
    use Promptable;
}

UseCheapestModel 和 UseSmartestModel 两个 Attribute 可以自动选择服务商最便宜或最强的模型，不需要记具体的模型名。

中间件

Agent 支持中间件机制，可以在请求发送前后插入自定义逻辑，比如日志记录：

复制代码

class LogPrompts
{
    public function handle(AgentPrompt $prompt, Closure $next)
    {
        Log::info('Prompting agent', ['prompt' => $prompt->prompt]);

        return $next($prompt)->then(function (AgentResponse $response) {
            Log::info('Agent responded', ['text' => $response->text]);
        });
    }
}

测试支持

SDK 为每个功能都提供了 fake() 方法和断言 API，测试时不需要真实调用 AI 服务商：

复制代码

SalesCoach::fake(['第一条响应', '第二条响应']);

// 执行业务逻辑...

SalesCoach::assertPrompted('分析这段...');
SalesCoach::assertNeverPrompted();

图像、音频、转录、Embeddings、Reranking、文件操作、向量存储都有对应的 fake 和断言方法。

服务商支持一览

功能	支持的服务商
文本对话	OpenAI、Anthropic、Gemini、Groq、xAI
图像生成	OpenAI、Gemini、xAI
语音合成	OpenAI、ElevenLabs
语音转录	OpenAI、ElevenLabs
向量嵌入	OpenAI、Gemini、Cohere、Jina
重排序	Cohere、Jina
文件管理	OpenAI、Anthropic、Gemini