人工智能代理模式
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Docker
- 运行环境要求
- Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# AI Agent Patterns
## When to Apply
- Creating a new agent class in `app/Ai/Agents/`
- Modifying `AgentResolver` action or prompt mappings
- Writing tests for agents (`::fake()`, `::assertPrompted()`)
- Working with SSE streaming in `AdminArticleAiController`
- Adding or changing apply block formats (`:::apply-body`, `:::apply-excerpt`)
- Debugging agent responses, conversation linking, or temperature behavior
## Documentation
Use `search-docs` for detailed Laravel AI SDK documentation before making changes.
## Agent Anatomy
Every agent implements `Agent & Conversational` (intersection type), uses three traits, and is configured via PHP attributes. All agents run on **Ollama** (Docker service), not OpenAI.
<code-snippet name="Complete Agent Class" lang="php">
// app/Ai/Agents/ArticleRefiner.php
namespace App\Ai\Agents;
use App\Ai\Agents\Concerns\HasArticleContext;
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Attributes\Timeout;
use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Stringable;
#[Model('llama3.2:3b')] // Ollama model — NOT OpenAI
#[Temperature(0.6)] // 0.3 (precise) to 0.8 (creative)
#[MaxTokens(4096)] // Fixed for all agents
#[Timeout(120)] // Fixed for all agents
class ArticleRefiner implements Agent, Conversational
{
use HasArticleContext, Promptable, RemembersConversations;
public function instructions(): Stringable|string
{
return <<<INSTRUCTIONS
You are an expert content editor...
{$this->articleContextBlock()}
{$this->applyBlockInstructions()}
INSTRUCTIONS;
}
}
</code-snippet>
**Temperature spectrum** — choose based on the agent's task precision:
| Temperature | Agent | Rationale |
|-------------|-------|-----------|
| 0.3 | GrammarChecker | Deterministic corrections, no creativity needed |
| 0.4 | Proofreader | Slight variation in feedback phrasing |
| 0.5 | SeoOptimizer | Balanced analysis with structured output |
| 0.6 | ArticleRefiner | Creative improvement while preserving voice |
| 0.8 | ArticleGenerator | Maximum creativity for original content |
**Non-conversational agents**: `HumanizerAgent` implements only `Agent` (NOT `Conversational`) because it processes text in a single pass without conversation memory. It does NOT use `HasArticleContext` — it has its own constructor signature.
## Content Generation Patterns
The `HasArticleContext` trait provides the constructor, context accessors, and prompt-building methods shared by all conversational agents.
<code-snippet name="HasArticleContext Trait" lang="php">
// app/Ai/Agents/Concerns/HasArticleContext.php
trait HasArticleContext
{
/**
* @param array{title: string, body: string, excerpt: string|null, content_type: string, category: string|null} $context
*/
public function __construct(
protected array $context = [],
) {}
protected function contextTitle(): string { return $this->context['title'] ?? ''; }
protected function contextBody(): string { return $this->context['body'] ?? ''; }
protected function contextExcerpt(): string { return $this->context['excerpt'] ?? ''; }
protected function contextContentType(): string { return $this->context['content_type'] ?? ''; }
protected function contextCategory(): string { return $this->context['category'] ?? ''; }
protected function estimateWordCount(string $body): int { return str_word_count(strip_tags($body)); }
}
</code-snippet>
**Prompt-building methods** (called in `instructions()`):
- `articleContextBlock()` — Returns article metadata (title, type, category, word count) + writing quality standards (banned phrases from `config('humanizer.banned_phrases')`, sentence variety rules)
- `applyBlockInstructions()` — Returns formatting rules for apply blocks
**Apply blocks** tell the frontend to auto-apply content back to the article editor:
<code-snippet name="Apply Block Format" lang="text">
// For replacing article body:
:::apply-body
<h2>Improved Heading</h2>
<p>The revised content goes here...</p>
:::
// For replacing article excerpt:
:::apply-excerpt
A compelling 1-2 sentence summary under 160 characters.
:::
</code-snippet>
**When to use apply blocks**: Only when the agent generates or rewrites replacement content. For feedback, suggestions, and analysis, agents respond in plain markdown without apply blocks. This distinction is enforced in each agent's `instructions()` prompt.
## AgentResolver Routing
`AgentResolver` is the single routing layer between HTTP endpoints and agent classes. All agent instantiation goes through it — never `new Agent()` directly.
<code-snippet name="AgentResolver Mapping Constants" lang="php">
// app/Ai/AgentResolver.php
class AgentResolver
{
protected const ACTION_AGENTS = [
'proofread' => Proofreader::class,
'grammar' => GrammarChecker::class,
'generate' => ArticleGenerator::class,
'refine' => ArticleRefiner::class,
'seo' => SeoOptimizer::class,
'excerpt' => SeoOptimizer::class,
];
protected const INLINE_AGENTS = [
'proofread' => Proofreader::class,
'grammar' => GrammarChecker::class,
];
// Each constant also has matching prompt templates:
// ACTION_PROMPTS and INLINE_PROMPTS
}
</code-snippet>
**Factory methods** — all return `Agent&Conversational` intersection type:
- `forAction(string $action, array $context)` — Quick actions (proofread, grammar, generate, refine, seo, excerpt)
- `forInlineReview(string $action, array $context)` — Inline editor actions (proofread, grammar only)
- `forChat(array $context)` — Conversational chat (always `ArticleRefiner`)
- `forSelectionChat(array $context)` — Freeform instruction on selected text (always `ArticleRefiner`)
**To add a new agent**:
1. Create the class in `app/Ai/Agents/` implementing `Agent, Conversational`
2. Use `HasArticleContext`, `Promptable`, `RemembersConversations` traits
3. Add to `ACTION_AGENTS` and/or `INLINE_AGENTS` in `AgentResolver`
4. Add a prompt template to `ACTION_PROMPTS` and/or `INLINE_PROMPTS`
5. Update `validActions()` or `validInlineActions()` if adding new action names
<code-snippet name="AgentResolver Factory Method" lang="php">
// Returns intersection type — both Agent AND Conversational
public static function forAction(string $action, array $context): Agent&Conversational
{
$class = self::ACTION_AGENTS[$action];
return new $class($context);
}
// Prompt includes body context appended to the template
public static function actionPrompt(string $action, array $context): string
{
$prompt = self::ACTION_PROMPTS[$action];
if ($action === 'generate') {
$prompt .= "\n\nArticle body to base generation on:\n".substr(strip_tags($context['body'] ?? ''), 0, 500);
} elseif (in_array($action, ['proofread', 'grammar', 'seo', 'refine'])) {
$prompt .= "\n\nArticle body:\n".($context['body'] ?? '');
} elseif ($action === 'excerpt') {
$prompt .= "\n\nArticle body:\n".substr(strip_tags($context['body'] ?? ''), 0, 2000);
}
return $prompt;
}
</code-snippet>
## Streaming & Conversation
The controller uses two streaming methods depending on whether conversations should persist.
<code-snippet name="Ephemeral Stream (No Conversation Linking)" lang="php">
// AdminArticleAiController::streamDirect()
private function streamDirect(Agent&Conversational $agent, string $prompt, User $user): StreamedResponse
{
$agent->forUser($user);
$streamable = $agent->stream($prompt);
return response()->stream(function () use ($streamable) {
try {
foreach ($streamable as $event) {
echo 'data: '.((string) $event)."\n\n";
if (ob_get_level() > 0) { ob_flush(); }
flush();
}
} catch (\Throwable $e) {
echo 'data: '.json_encode(['type' => 'error', 'message' => $e->getMessage()])."\n\n";
flush();
report($e);
}
echo "data: [DONE]\n\n";
flush();
}, 200, [
'Content-Type' => 'text/event-stream',
'X-Accel-Buffering' => 'no',
'Cache-Control' => 'no-cache',
'Connection' => 'keep-alive',
]);
}
</code-snippet>
**Conversation linking** (for chat, not inline actions):
- New conversation: `$agent->forUser($user)` → starts fresh
- Resume: `$agent->continue($conversationId, as: $user)` → resumes existing
- After streaming: `$agent->currentConversation()` → get conversation ID
- Link to article: Update `agent_conversations.article_id` via `.then()` callback on the streamable
- Conversations stored in `agent_conversations` + `agent_conversation_messages` tables (UUID PKs)
**Generate action is special**: Dispatches `ProcessArticle` job instead of streaming. Returns `202 Accepted` with JSON. The job runs generation server-side, humanizes via `TextHumanizer`, and broadcasts progress via Reverb.
<code-snippet name="Conversation Linking Pattern" lang="php">
// AdminArticleAiController::streamAgent() — links conversation to article after streaming
if (! empty($validated['conversation_id'])) {
$agent->continue($validated['conversation_id'], as: $user);
} else {
$agent->forUser($user);
}
$streamable = $agent->stream($prompt);
$articleId = $validated['article_id'] ?? null;
$streamable->then(function () use ($agent, $articleId) {
$conversationId = $agent->currentConversation();
if ($conversationId && $articleId) {
DB::table('agent_conversations')
->where('id', $conversationId)
->whereNull('article_id')
->update(['article_id' => $articleId]);
}
});
</code-snippet>
## Testing
Each agent class has its own `::fake()` and `::assertPrompted()` static methods provided by the Laravel AI SDK. Always fake the specific agent class, not a generic mock.
<code-snippet name="Agent Testing Patterns" lang="php">
// tests/Feature/Admin/AdminArticleAiControllerTest.php
use App\Ai\Agents\ArticleRefiner;
use App\Ai\Agents\Proofreader;
// Helper function for valid context (reuse across tests)
function validContext(): array
{
return [
'title' => 'Test Article',
'body' => '<p>Test article body with enough content.</p>',
'excerpt' => 'A test excerpt',
'content_type' => 'general',
'category' => 'Technology',
];
}
// Fake an agent with a canned response
test('chat endpoint streams response', function () {
$admin = User::factory()->admin()->create();
ArticleRefiner::fake(['Improved content here']);
$this->actingAs($admin)
->postJson('/admin/articles/ai/chat', [
'message' => 'Improve this article',
'context' => validContext(),
])->assertOk();
ArticleRefiner::assertPrompted('Improve this article');
});
// Fake an agent for quick actions
test('action endpoint resolves correct agent', function () {
$admin = User::factory()->admin()->create();
Proofreader::fake(['Feedback here']);
$this->actingAs($admin)
->postJson('/admin/articles/ai/action', [
'action' => 'proofread',
'context' => validContext(),
])->assertOk();
Proofreader::assertPrompted(fn ($prompt) =>
str_contains($prompt->prompt, 'Review the current article')
);
});
// Generate action uses Queue::fake() instead
test('generate action dispatches job', function () {
Queue::fake();
$admin = User::factory()->admin()->create();
$article = Article::factory()->create();
$this->actingAs($admin)
->postJson('/admin/articles/ai/action', [
'action' => 'generate',
'article_id' => $article->id,
'context' => validContext(),
])->assertAccepted();
Queue::assertPushed(ProcessArticle::class);
});
</code-snippet>
**Key testing patterns**:
- `AgentName::fake(['response text'])` — Synchronous fake with canned response
- `AgentName::fake()` — Empty response fake (for validation tests)
- `AgentName::assertPrompted('substring')` — Assert the prompt contained text
- `AgentName::assertPrompted(fn ($prompt) => ...)` — Assert with closure for complex matching
- `Queue::fake()` + `Queue::assertPushed(ProcessArticle::class)` — For the generate action
- `$this->withoutMiddleware(ValidateCsrfToken::class)` — For JSON API tests
- Conversation history tests must seed `agent_conversations` and `agent_conversation_messages` tables directly with all required JSON columns (attachments, tool_calls as empty arrays/objects)
## Common Pitfalls
- **Thinking-capable models crash the SDK**: Avoid models like `qwen3` that emit `ThinkingCompleteEvent` — the Laravel AI SDK doesn't handle it and throws an unrecoverable exception. Stick to `llama3.2:3b` or similar non-thinking models.
- **Ollama, not OpenAI**: Agents use `#[Model('llama3.2:3b')]` which runs on the Ollama Docker service. Don't confuse this with the global `config('ai.default_provider')` which is for different use cases. The model attribute is the Ollama model name.
- **Temperature mismatches**: Using high temperature (0.8) for grammar checking produces inconsistent corrections. Using low temperature (0.3) for content generation produces flat, repetitive output. Match temperature to task precision — see the spectrum table above.
- **Missing context fields cause silent failures**: The context array has 5 fields (`title`, `body`, `excerpt`, `content_type`, `category`). The `body` field uses `['present', 'nullable']` validation — it must be present in the request even if null. Controllers coerce null to empty string: `$validated['context']['body'] = $validated['context']['body'] ?? ''`.
- **Forgetting to register in AgentResolver**: Creating a new agent class without adding it to `ACTION_AGENTS` or `INLINE_AGENTS` in `AgentResolver` means it's unreachable from the controller. Also add a prompt template to `ACTION_PROMPTS`/`INLINE_PROMPTS` and update `validActions()`/`validInlineActions()`.
---
> Source: [ABilenduke/copilot-developer](https://github.com/ABilenduke/copilot-developer) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
何时申请
文档
特工解剖
内容生成模式
AgentResolver路由
文件/命令 -> app/Ai/Agents/ · AgentResolver · ::fake() · ::assertPrompted() · AdminArticleAiController · :::apply-body · :::apply-excerpt · search-docs
内容校验值 -> 1b5428259ff7
当前原文的自动摘译,尚未人工审校。
何时申请
在
app/Ai/Agents/中创建新代理类 修改AgentResolver操作或提示映射 为代理编写测试 (::fake()、::assertPrompted()) 在AdminArticleAiController中使用 SSE 流 添加或更改应用块格式 (:::apply-body、:::apply-excerpt)文档
在进行更改之前,请使用
search-docs获取详细的 Laravel AI SDK 文档。特工解剖
每个代理都实现
Agent & Conversational(交叉类型),使用三个特征,并通过 PHP 属性进行配置。所有代理都在 Ollama(Docker 服务)上运行,而不是 OpenAI。 <code-snippet name="完整代理类" lang="php"> // app/Ai/Agents/ArticleRefiner.php 命名空间 App\Ai\Agents;使用 App\Ai\Agents\Concerns\HasArticleContext;内容生成模式
HasArticleContext特征提供了所有会话代理共享的构造函数、上下文访问器和提示构建方法。 <code-snippet name="HasArticleContext Trait" lang="php"> // app/Ai/Agents/Concerns/HasArticleContext.php 特征 HasArticleContext {AgentResolver路由
AgentResolver是 HTTP 端点和代理类之间的单一路由层。所有代理实例化都经过它——从不直接new Agent()。 <code-snippet name="AgentResolver 映射常量" lang="php"> // app/Ai/AgentResolver.php class AgentResolver {