Module @celljs/ai-agent - v4.1.0

Cell - AI Agent Component

基于 pi-agent-core 的通用 agent：agent 循环、并行工具调用、事件流，不带编码工具和文件系统权限，适合在业务里做助手。模型来自 @celljs/ai-pi。需要读写代码、执行命令的场景用 @celljs/ai-coding-agent。

工具写成 AgentTool 组件，可以直接用注入的服务；同样的组件也是编码会话的工具；
AgentFactory 按 cell.ai.agent 创建 pi-agent-core 的 Agent；
AgentEventUtil.stream() 把 agent（或编码会话）的事件写成 Server-Sent Events。

pi-agent-core 用动态 import() 加载，需要 Node.js >= 22.19 或 Bun。

配置

cell:
  ai:
    agent:
      model: anthropic/claude-sonnet-4-5   # pi-ai 的 <provider>/<model id>；默认第一个有凭据的模型
      systemPrompt: You are the support assistant of ACME.
      thinkingLevel: low
      tools: [find_order, refund]          # AgentTool 组件名；默认全部
      toolExecution: parallel              # 或 sequential

API key 在 cell.ai.pi.apiKeys 或服务商的环境变量里配置。

使用

import { AgentEventUtil, AgentFactory, AgentTool } from '@celljs/ai-agent';
import { Autowired, Component } from '@celljs/core';
import { Body, Controller, Post, Res } from '@celljs/mvc/lib/node';
import { OrderService } from './order-service';

@Component(AgentTool)
export class FindOrderTool implements AgentTool {
    readonly name = 'find_order';
    readonly label = 'Find order';
    readonly description = 'Finds an order by its number.';
    readonly parameters = { type: 'object', properties: { number: { type: 'string' } }, required: [ 'number' ] };

    @Autowired(OrderService)
    protected readonly orderService: OrderService;

    async execute(_toolCallId: string, params: any) {
        const order = await this.orderService.find(params.number);
        return { content: [ { type: 'text' as const, text: JSON.stringify(order) } ], details: {} };
    }
}

@Controller('assistant')
export class AssistantController {
    @Autowired(AgentFactory)
    protected readonly agentFactory: AgentFactory;

    @Post()
    async ask(@Body('text') text: string, @Res() response: any): Promise<void> {
        const agent = await this.agentFactory.create();
        await AgentEventUtil.stream(agent, response, () => agent.prompt(text));
    }
}

create() 的参数（model、systemPrompt、thinkingLevel、tools）覆盖配置；传 messages（之前保存的 agent.state.messages）可以继续一段对话。工具名不存在时报 AgentToolNotFoundError，没有可用模型时报 AgentModelMissingError。拿到的 Agent 是 pi-agent-core 原生对象：prompt、steer、followUp、abort、subscribe、state 见其文档。

SSE 每帧是 event: <type>\ndata: <JSON>，message_update 只带增量和用量，与 pi coding agent 的 JSON 模式一致；失败时发 { "type": "error", "message": "..." }。

测试

@celljs/ai-agent/lib/node/test 的 createAgentTestContainer(options, ...modules) 用 FauxPiModels 作默认模型：faux.reply('文本' | { tool, args } | { error }) 编排回复，faux.contexts 记录每次请求。