使用 Laravel AI SDK 构建 AI Agent…

在 Laravel 13.x/PHP 8.3+ 项目中用 laravel/ai 实现 AI agents、工具、媒体生成、embeddings、向量搜索和 AI 测试时，按 17 条规则快速落地。

适用场景

解决思路

1. 按优先级应用规则：Agents 为 CRITICAL，Tools、Embeddings & Search、Testing 为 HIGH，Media Generation、Files & Storage、Infrastructure 为 MEDIUM。
2. 创建和配置 Agent：用 artisan 创建 Agent，并通过 PHP attribute 配置 Agent。
3. 提示 Agent：使用 prompt 提示 Agent，传入对话上下文，并用 RemembersConversations 保留对话。
4. 结构化输出：让 Agent 按 JSON schema 输出结构化结果。
5. 流式与异步：实现流式响应、广播响应和队列处理响应。
6. Agent 中间件：为 Agent 配置中间件管道。
7. 匿名 Agent：使用匿名 Agent 做快速交互。
8. 自定义工具：创建自定义工具，定义 schema 和 handle 方法。
9. 提供方工具：使用 WebSearch、WebFetch、FileSearch、SimilaritySearch。
10. 生成与缓存 embeddings：生成、存储并缓存向量 embeddings。
11. 重排：按相关性对 documents 和 collections 做 rerank。
12. 生成图片：生成、存储并队列处理图片。
13. 音频转写：实现文本转语音和语音转文本。
14. 文件与向量存储：为 RAG 存储文件并使用 vector stores。
15. 基础设施故障转移：配置自动 provider failover 以提高韧性。
16. 测试 Agents：使用 fake agents、断言 prompts、阻止 stray prompts。
17. 测试 Media：fake 图片、音频和 transcriptions。
18. 测试 Data：fake embeddings、reranking、files 和 vector stores。
19. 创建 Agent 示例：定义类实现 Laravel\Ai\Contracts\Agent，使用 Laravel\Ai\Promptable，并在 instructions() 中返回指令。
20. 提示 Agent 示例：调用 SalesCoach::make()->prompt('Analyze this sales transcript...')，并返回 (string) $response。
21. 生成图片示例：调用 Image::of('A donut sitting on the kitchen counter')->landscape()->generate()，再用 $image->store() 存储。
22. 生成 embeddings 示例：调用 Str::of('Napa Valley has great wine.')->toEmbeddings()。
23. 测试示例：调用 SalesCoach::fake(['First response', 'Second response'])，再调用 SalesCoach::make()->prompt('Analyze this...')，最后调用 SalesCoach::assertPrompted('Analyze this...')。
24. 阅读各规则文件：每个规则文件包含 YAML frontmatter（title、impact、tags）、原因说明、Bad Example、Good Example，以及 Laravel 13 和 PHP 8.3 的上下文与引用。
25. 查阅完整编译文档：查看 AGENTS.md 获取展开后的完整指南。

适用边界 · 注意事项

• 不适用于未安装 laravel/ai、不是 Laravel 13.x 或 PHP 版本低于 8.3 的项目。
• 不适用于不需要 AI agents、工具、媒体生成、embeddings、向量搜索或 AI 测试的普通任务。
• 不适用于使用其他 AI SDK/框架且不准备引入 Laravel AI SDK 的项目。