@celljs/ai-agent 4.6.1 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.en.md +68 -0
  2. package/package.json +4 -4
package/README.en.md ADDED
@@ -0,0 +1,68 @@
1
+ # Cell - AI Agent Component
2
+
3
+ A general-purpose agent based on [pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core): agent loop, parallel tool execution, and event streams—without code editing or file system permissions, suitable as an assistant in business logic. Models come from [@celljs/ai-pi](../ai-pi). Use [@celljs/ai-coding-agent](../ai-coding-agent) for code reading/writing or command execution scenarios.
4
+
5
+ - Tools are written as `AgentTool` components and can directly use injected services; the same components also serve as tools in a coding session.
6
+ - `AgentFactory` creates an `Agent` from pi-agent-core per `ai.agent` configuration.
7
+ - `AgentEventUtil.stream()` writes agent (or coding session) events as Server-Sent Events.
8
+
9
+ pi-agent-core loads with dynamic `import()` and requires Node.js >= 22.19 or Bun.
10
+
11
+ ## Configuration
12
+
13
+ ```yaml
14
+ ai:
15
+ agent:
16
+ model: anthropic/claude-sonnet-4-5 # <provider>/<model id> from pi-ai; defaults to first available model with credentials
17
+ systemPrompt: You are the support assistant of ACME.
18
+ thinkingLevel: low
19
+ tools: [find_order, refund] # AgentTool component names; defaults to all
20
+ toolExecution: parallel # or sequential
21
+ ```
22
+
23
+ API keys are configured in `ai.pi.apiKeys` or the provider's environment variables.
24
+
25
+ ## Usage
26
+
27
+ ```typescript
28
+ import { AgentEventUtil, AgentFactory, AgentTool } from '@celljs/ai-agent';
29
+ import { Autowired, Component } from '@celljs/core';
30
+ import { Body, Controller, Post, Res } from '@celljs/mvc/lib/node';
31
+ import { OrderService } from './order-service';
32
+
33
+ @Component(AgentTool)
34
+ export class FindOrderTool implements AgentTool {
35
+ readonly name = 'find_order';
36
+ readonly label = 'Find order';
37
+ readonly description = 'Finds an order by its number.';
38
+ readonly parameters = { type: 'object', properties: { number: { type: 'string' } }, required: [ 'number' ] };
39
+
40
+ @Autowired(OrderService)
41
+ protected readonly orderService: OrderService;
42
+
43
+ async execute(_toolCallId: string, params: any) {
44
+ const order = await this.orderService.find(params.number);
45
+ return { content: [ { type: 'text' as const, text: JSON.stringify(order) } ], details: {} };
46
+ }
47
+ }
48
+
49
+ @Controller('assistant')
50
+ export class AssistantController {
51
+ @Autowired(AgentFactory)
52
+ protected readonly agentFactory: AgentFactory;
53
+
54
+ @Post()
55
+ async ask(@Body('text') text: string, @Res() response: any): Promise<void> {
56
+ const agent = await this.agentFactory.create();
57
+ await AgentEventUtil.stream(agent, response, () => agent.prompt(text));
58
+ }
59
+ }
60
+ ```
61
+
62
+ Parameters to `create()` (`model`, `systemPrompt`, `thinkingLevel`, `tools`) override configuration; pass `messages` (previously saved `agent.state.messages`) to continue a conversation. Throws `AgentToolNotFoundError` if a tool name does not exist, and `AgentModelMissingError` if no model is available. The `Agent` you get is a native pi-agent-core object: see its documentation for `prompt`, `steer`, `followUp`, `abort`, `subscribe`, and `state`.
63
+
64
+ Each SSE frame is `event: <type>\ndata: <JSON>`; `message_update` carries only increments and usage, matching pi coding agent's JSON mode; on failure, sends `{ "type": "error", "message": "..." }`.
65
+
66
+ ## Testing
67
+
68
+ `@celljs/ai-agent/lib/node/test` provides `createAgentTestContainer(options, ...modules)` with `FauxPiModels` as the default model: use `faux.reply('text' | { tool, args } | { error })` to script responses, and `faux.contexts` records each request.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@celljs/ai-agent",
3
- "version": "4.6.1",
3
+ "version": "4.7.0",
4
4
  "description": "General-purpose pi agents (pi-agent-core) with tools as Cell components",
5
5
  "keywords": [
6
6
  "cell-component"
@@ -33,12 +33,12 @@
33
33
  "watch": "tsc -b -w --preserveWatchOutput"
34
34
  },
35
35
  "dependencies": {
36
- "@celljs/ai-pi": "4.6.1",
37
- "@celljs/core": "4.6.1",
36
+ "@celljs/ai-pi": "4.7.0",
37
+ "@celljs/core": "4.7.0",
38
38
  "@earendil-works/pi-agent-core": "^1.5.0"
39
39
  },
40
40
  "devDependencies": {
41
- "@celljs/ai-core": "4.6.1"
41
+ "@celljs/ai-core": "4.7.0"
42
42
  },
43
43
  "publishConfig": {
44
44
  "access": "public"