# Actoviq Agent SDK：受Claude Code启发的多工具代理开发框架

> 深入解析Actoviq Agent SDK——一个从Claude Code、Codex和DeepAgents经验中汲取灵感的实验性Node.js/TypeScript代理SDK，支持多工具、多会话和桥接辅助的代理工作流。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-01T07:45:09.000Z
- 最近活动: 2026-04-01T07:52:51.518Z
- 热度: 159.9
- 关键词: AI代理, TypeScript, MCP, Claude Code, SDK, Node.js, 多工具, 会话管理
- 页面链接: https://www.zingnex.cn/forum/thread/actoviq-agent-sdk-claude-code
- Canonical: https://www.zingnex.cn/forum/thread/actoviq-agent-sdk-claude-code
- Markdown 来源: ingested_event

---

# Actoviq Agent SDK：受Claude Code启发的多工具代理开发框架

## 项目背景与动机

随着AI编程助手如Claude Code、GitHub Copilot和各类Codex变体的普及，开发者们逐渐意识到：单一的对话式交互已无法满足复杂软件开发的需求。真正的生产力提升来自于能够协调多种工具、管理长期会话、并在结构化工作流中自主运行的代理系统。

Actoviq Agent SDK正是基于这一洞察诞生的实验性项目。它从Claude Code、OpenAI Codex和DeepAgents等优秀工具的经验中汲取精华，构建了一个独立的多工具、多会话代理SDK，旨在为开发者提供构建实用AI代理的基础设施。

## 核心架构：双层设计

Actoviq采用独特的双层架构，满足不同使用场景的需求：

### 1. 清洁SDK层（Clean SDK Layer）

面向应用集成的轻量级SDK，提供：

- `run()` 和 `stream()` 方法用于同步和流式交互
- 持久化会话管理
- 基于Zod模式的工具定义
- MCP（Model Context Protocol）服务器支持

### 2. 运行时桥接层（Runtime Bridge Layer）

提供Actoviq原生非TUI代理行为的桥接层，包含：

- 内置工具池（Read、Write、Edit、Glob、Grep）
- 技能（Skills）系统
- 子代理（Subagents）支持
- 原生会话和上下文行为

这种分层设计让开发者可以根据需求选择合适的工作模式——既可以快速集成轻量级SDK，也可以利用完整的运行时能力构建复杂代理。

## 关键特性解析

### 工具系统与MCP支持

Actoviq的工具系统基于Zod模式定义，提供类型安全的工具调用：

```typescript
const addNumbers = tool(
  {
    name: 'add_numbers',
    description: 'Add two numbers together.',
    inputSchema: z.object({ a: z.number(), b: z.number() }),
  },
  async ({ a, b }) => ({ sum: a + b }),
);
```

同时，SDK原生支持MCP服务器，可以连接本地stdio服务器或远程HTTP/WebSocket端点，实现工具生态的无限扩展。

### 会话管理与上下文压缩

Actoviq提供持久化会话机制，支持跨交互的上下文保持：

```typescript
const session = await sdk.createSession({ title: 'Demo Session' });
await session.send('Remember that my project codename is Sparrow.');
const reply = await session.send('What is my project codename?');
```

对于长期运行的会话，SDK还提供了上下文压缩机制，通过`sdk.context.compact()`方法智能总结当前进展，避免上下文窗口溢出。

### 桥接运行时的高级抽象

桥接SDK提供了更高级的抽象，简化代理和技能的使用：

```typescript
const reviewer = sdk.useAgent('general-purpose');
const reviewResult = await reviewer.run('Explain what this repository is for.');

const debugSkill = sdk.useSkill('debug');
const debugResult = await debugSkill.run('summarize the current runtime configuration');
```

这些封装让开发者无需手动处理代理和斜杠命令的细节，专注于业务逻辑的实现。

### 工作区生命周期管理

Actoviq内置了工作区管理助手，支持创建隔离的目录环境：

- `createWorkspace()`：创建标准工作区
- `createTempWorkspace()`：创建临时工作区（可带前缀和复制源）
- `createGitWorktreeWorkspace()`：基于Git worktree创建工作区

这种设计特别适合需要隔离环境的CI/CD场景或多租户应用。

## 与上游工具的关系

Actoviq明确将自己定位为"独立开发"的项目，而非任何现有工具的分支或包装。它从以下工具中学习：

| 工具 | Actoviq借鉴的方面 |
|------|-------------------|
| Claude Code | 会话管理、工具调用模式、人机协作理念 |
| OpenAI Codex | 代理工作流编排、多文件编辑策略 |
| DeepAgents | 多代理协作、技能抽象层 |

同时，Actoviq通过"vendored runtime"机制集成了上游Actoviq运行时的能力，包括文件工具、技能系统和子代理支持。这种设计既保持了SDK的轻量性，又提供了完整的功能覆盖。

## 技术实现细节

### 凭证解析优先级

Actoviq采用清晰的多层凭证解析策略：

1. 显式传递给`createAgentSdk()`的选项
2. 进程环境变量
3. 通过`loadJsonConfigFile()`预加载的JSON文件
4. `~/.actoviq/settings.json`（通过`loadDefaultActoviqSettings()`）

支持的配置项包括API密钥、认证令牌、基础URL和模型选择等。

### 文件工具的实现

Actoviq的文件工具（Read、Write、Edit、Glob、Grep）提供了与上游运行时一致的体验：

- **Read**：支持分页读取（默认2000行），避免大文件加载导致的内存问题
- **Write**：原子写入，确保文件完整性
- **Edit**：基于文本替换的精确编辑
- **Glob**：模式匹配文件查找
- **Grep**：文本搜索，优先使用系统rg二进制文件

### 会话存储与发现

Actoviq使用`.actoviq/projects`目录存储会话数据，提供完整的CRUD操作：

```typescript
const sessions = await listActoviqBridgeSessions({ limit: 10 });
const info = await getActoviqBridgeSessionInfo(sessionId);
const messages = await getActoviqBridgeSessionMessages(sessionId);
```

这种设计让开发者可以构建会话管理UI、审计日志或协作功能。

## 使用场景与示例

### 快速开始

```typescript
import { createAgentSdk, loadDefaultActoviqSettings } from 'actoviq-agent-sdk';

await loadDefaultActoviqSettings();
const sdk = await createAgentSdk();

const result = await sdk.run('Introduce yourself in one sentence.');
console.log(result.text);
await sdk.close();
```

### 流式交互

```typescript
const stream = session.stream(prompt);
for await (const event of stream) {
  if (event.type === 'response.text.delta') {
    process.stdout.write(event.delta);
  }
}
const result = await stream.result;
```

### MCP服务器集成

```typescript
const sdk = await createAgentSdk({
  mcpServers: [
    stdioMcpServer({
      name: 'filesystem',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
    }),
  ],
});
```

## 当前状态与路线图

### 已实现功能

- npm包发布和安装
- 核心SDK流程：run()、stream()、sessions、tools、MCP
- 桥接运行时流程：内置工具、运行时内省、交互式演示
- 高级代理、技能和上下文助手
- 文件工具：Read、Write、Edit、Glob、Grep
- 工作区生命周期助手
- 示例、测试、构建和冒烟检查

### 路线图

- 深化上下文、内存和压缩控制
- 添加更丰富的代理和技能元数据API
- 添加更丰富的模板和沙箱编排助手
- 完善CI工作流、发布说明和贡献者文档

## 技术选型考量

### 为什么选择TypeScript/Node.js？

Actoviq选择TypeScript作为主要实现语言，基于以下考量：

1. **生态成熟度**：Node.js拥有最丰富的NPM包生态，特别是MCP服务器生态
2. **类型安全**：TypeScript提供编译时类型检查，减少运行时错误
3. **开发体验**：现代IDE对TypeScript的支持优于大多数其他语言
4. **桥接便利**：通过Bun执行vendored运行时CLI，实现无缝集成

### 与Python代理框架的对比

相比Python生态中的代理框架（如LangChain、AutoGPT），Actoviq的优势在于：

- 更轻量的运行时（单个Go二进制 vs Python解释器+依赖）
- 更好的类型安全（TypeScript vs Python的动态类型）
- 原生的MCP支持（标准化的工具协议）

但Python生态在ML/DS领域的深度仍然是Actoviq需要追赶的。

## 结语：代理开发的新选择

Actoviq Agent SDK代表了AI代理开发工具的新方向——不是构建一个"万能"的代理，而是提供构建代理的基础设施。它的双层架构、MCP支持、会话管理和工作区抽象，为开发者提供了构建定制化AI代理所需的全部工具。

对于已经熟悉Claude Code或类似工具、希望构建自己的代理应用的开发者来说，Actoviq提供了一个值得探索的起点。虽然项目仍处于Pre-1.0的快速迭代阶段，但其清晰的架构设计和活跃的开发节奏，预示着良好的发展前景。

---

**项目信息**
- GitHub: https://github.com/DeconBear/actoviq-agent-sdk
- NPM: actoviq-agent-sdk
- 许可证: MIT
- 状态: 公开预览版，活跃开发中