@cicctencent/agent-core

内部库，仅供项目内部使用，不对外发布。

AI Agent 核心引擎，提供 ReAct 循环编排、多 LLM 供应商抽象、工具注册与执行、MCP 协议集成、Skill 路由、安全守卫、渐进式记忆管道、A2A 协议互操作（流式事件透传），以及工具风险评估、审批管理、运行注册表、引擎复用池、JSON 存储、可观测性日志、多模态输入、对话历史持久化、Token 用量追踪与成本管控、声明式 Agent 定义（YAML front matter）、Anthropic Prompt 缓存优化、SSE 断流中断检测、非破坏性上下文投影（Context Collapse）、工作空间笔记中间件、知识库 RAG（KnowledgeBase + EmbeddingProvider）、向量检索（VectorIndex）、邮件发送接口（EmailProvider）、日历事件类型（CalendarEvent/CalendarStore）、批处理（BatchProvider，OpenAI Batch API）、文件上传与管理（FileProvider，OpenAI Files API）等应用级能力。

文档

• 完整 API 文档 — 所有模块的接口说明和使用示例
• v0.2 升级指南 — 新增 12 个下沉模块的集成指南
• Runtime 下沉与迁移指南 — Runtime Builder、RunController、默认沙箱、A2A Server Helper 与使用方迁移边界

快速开始

pnpm add @cicctencent/agent-core

import { AgentEngine, createLLMProvider, ToolRegistry, ContextManager } from '@cicctencent/agent-core';

const llm = createLLMProvider({ provider: 'openai', model: 'gpt-4o', apiKey: process.env.OPENAI_API_KEY! });
const toolRegistry = new ToolRegistry();
const engine = new AgentEngine({ llmProvider: llm, toolRegistry, contextManager: new ContextManager(), maxIterations: 10 });

for await (const event of engine.run({ sessionId: 'session-001', message: 'Hello' })) {
  if (event.type === 'message') process.stdout.write(event.content);
  if (event.type === 'done') console.log('\nDone:', event.content);
}

A2A 协议集成

支持将远程 A2A Agent 包装为 SubAgentRunner，与本地 Specialist 并列注册到 delegate_task：

import { A2AClient, createA2ARemoteRunner, createDelegateTool } from '@cicctencent/agent-core';

const client = new A2AClient();
const card = await client.discoverAgent('https://remote-agent.example.com');

const remoteRunner = createA2ARemoteRunner({
  agentUrl: card.url,
  name: `[Remote] ${card.name}`,
  description: card.description,
  streaming: card.capabilities.streaming,
  client,
  skillId: 'specialist_123',  // 可选，供服务端路由到对应的 specialist
});

const delegateTool = createDelegateTool([localSpecialist, remoteRunner]);
if (delegateTool) registry.register(delegateTool);

核心特性：

• 事件透传：Core 不对 A2A SSE 事件做过滤，服务端发的所有事件均透传给调用方
• 流式自动降级：远程不支持流式时自动回退到同步模式
• 取消支持：流式传输支持 AbortSignal 外部取消
• 心跳重置超时：逐次读取超时，心跳可重置计时器，适合长时间任务

详见 A2A 协议文档。

多模态输入

Message.content 支持 string | ContentPart[] | null，可传图片/文件给 Vision 模型：

import type { ContentPart } from '@cicctencent/agent-core';

const content: ContentPart[] = [
  { type: 'text', text: '这张图片里是什么？' },
  { type: 'image', source: 'data:image/png;base64,iVBOR...', mimeType: 'image/png' },
];

for await (const event of engine.run({ sessionId: 's1', message: content })) {
  if (event.type === 'message') process.stdout.write(event.content);
}

• TextPart — 文本片段
• ImagePart — 图片（base64 data URI 或 URL），OpenAI/Anthropic Provider 自动适配
• FilePart — 文件内容（文本注入上下文）
• extractTextFromContent() — 从多模态内容提取纯文本

对话历史持久化

通过 HistoryPersistence 接口实现 JSONL append-only 持久化，服务重启后自动恢复：

import { JsonlHistoryPersistence } from '@cicctencent/agent-core';

const persistence = new JsonlHistoryPersistence({ dir: 'history' });
const engine = new AgentEngine({
  // ...
  historyPersistence: persistence,
});

// 重启后恢复
await engine.loadHistory('session-001');

// 历史操作（自动同步持久化）
engine.truncateHistory('session-001', 10);  // 截断到第 10 条
engine.forkHistory('session-001', 'session-002', 5);  // 从第 5 条分叉

Token 用量追踪与成本管控

import { InMemoryUsageTracker } from '@cicctencent/agent-core';

const tracker = new InMemoryUsageTracker();
const engine = new AgentEngine({
  // ...
  usageTracker: tracker,
  tokenBudget: { maxTokens: 500_000, onExceed: 'warn' },
});

// 查询统计
const stats = tracker.stats({ startTime: Date.now() - 86400000 });
console.log(`总 Token: ${stats.totalTokens}, 成本: $${stats.totalCost}`);

// 预算检查
const budget = tracker.checkBudget('session-001', { maxTokens: 100_000 });
if (budget.exceeded) console.warn('预算超限！');

• 内置 20+ 常见模型定价表（TokenPricing）
• calculateCost(provider, model, usage) 自动计算成本
• 按 Provider/Model 分组统计
• 预算控制：超限时 warn（日志告警）或 abort（中止执行）

构建

pnpm typecheck   # 类型检查
pnpm build       # 生成 .d.ts

运行时要求

Node.js >= 22