AgentDock

一句话定位

一个 TypeScript 编写、后端优先（backend-first）的开源生产级 agent 与 workflow 构建平台，核心信条是 configurable determinism（可配置确定性）：用统一的 node-based 架构（BaseNode / AgentNode / Tools-as-Nodes）把 LLM 智能与确定性工作流缝合起来——既能让 agent 自由推理，又能用 orchestration step/sequence 把工具调用约束成可预测的执行路径。框架本体（agentdock-core）与一个完整的 Next.js 参考客户端分离，可独立嵌入任意 Node.js 后端。

设计理念 / 顶层架构

AgentDock 是 monorepo：agentdock-core/（provider-independent 的核心库，本笔记焦点）+ 根目录的 Next.js 开源客户端（src/，core 的消费者/参考实现）+ agents/（35+ JSON 模板）。核心设计取舍：

• 一切皆 Node：BaseNode（agentdock-core/src/nodes/base-node.ts:55）是抽象基类，声明 execute()、输入/输出 ports（NodePort）、元数据、以及节点间的 MessageBus 通信。AgentNode（nodes/agent-node.ts:107，type = 'core.agent'）是编排 LLM+工具的专用核心节点；工具与自定义逻辑都被建模为扩展 BaseNode 的节点。
• configurable determinism：非确定性的 AgentNode（LLM 推理）可以触发确定性的 sub-workflow / tool 序列；通过 orchestration 配置控制”哪些部分走 LLM 推理”，从而在创造性与可预测性之间取舍（README §Configurable Determinism）。
• 声明式 Agent = JSON 模板：agent 由 AgentConfig（types/agent-config.ts:41，Zod 校验）定义——personality（system prompt）、nodes（启用的能力/工具名）、nodeConfigurations（每个 provider/工具的配置）、orchestration（step/sequence/条件）、chatSettings（历史策略）。模板见 agents/*/template.json。
• provider-independent：CoreLLM（llm/core-llm.ts:84）在 Vercel AI SDK（ai 包）之上做统一封装，createLLM 工厂按 provider 路由到各 adapter（anthropic/openai/google/groq/deepseek/cerebras）。
• 入口 API：import { AgentNode, ... } from 'agentdock-core'（src/index.ts）。new AgentNode(id, { apiKey, agentConfig }) 后调用 agentNode.handleMessage({ messages, sessionId, orchestrationManager })，返回 Vercel AI SDK 的流式结果（AgentDockStreamResult），由调用方（API 路由/适配器）消费流并构造 HTTP 响应。

最小示例（基于 README 的 node-based / handleMessage 范式 + AgentConfig 形态）：

import { AgentNode, createOrchestrationManager } from 'agentdock-core';

// 1) 声明式 agent 配置（等价于 agents/*/template.json）
const agentConfig = {
  version: '1.0',
  agentId: 'assistant',
  name: 'Assistant',
  description: 'A helpful assistant',
  personality: 'You are a helpful assistant.',
  nodes: ['llm.anthropic', 'search', 'think'], // 启用的工具节点
  nodeConfigurations: {
    'llm.anthropic': { model: 'claude-sonnet-4-20250514', temperature: 0.7 }
  },
  chatSettings: { historyPolicy: 'all' },
  options: { maxSteps: 5 } // 多步工具调用上限
};

// 2) 构造 AgentNode（运行时依赖 OrchestrationManager 经方法注入）
const agent = new AgentNode('assistant', {
  apiKey: process.env.ANTHROPIC_API_KEY!,
  provider: 'anthropic',
  agentConfig
});

const orchestrationManager = createOrchestrationManager();

// 3) 处理一条消息，得到 Vercel AI SDK 流式结果
const result = await agent.handleMessage({
  sessionId: 'session-1',
  orchestrationManager,
  messages: [{ role: 'user', content: 'Search for TS agent frameworks' }]
});
// result 是 streamText 结果：调用方消费 result 流并返回给前端

组件实现（横向逐项）

设计权衡与特性

• configurable determinism 是核心卖点：与多数”放手让 LLM 自主 ReAct”的框架不同，AgentDock 用声明式 orchestration step + sequence（强制工具顺序）+ conditions（tool_used/sequence_match 触发状态转移）把工具调用收束成可预测路径——getAllowedTools（orchestration/core.ts:351）每轮按当前 step 过滤 LLM 可见工具。即”非确定性 agent 包裹确定性 workflow”。
• node-based 单一抽象：agent、tool、自定义逻辑全部是 BaseNode，靠 registry 组装、靠 ports/MessageBus 连接。代价是抽象偏重、上手需理解 node/registry/orchestration 三件套；好处是统一可组合、为可视化 workflow builder（AgentDock Pro）铺路。
• backend-first + provider-independent：核心库刻意不绑死前端/服务形态，streamText 结果直接交给宿主（Next.js 客户端是参考实现，可一键 Vercel 部署）。LLM 全走 Vercel AI SDK，新增 provider 只需加 adapter。
• 记忆系统是重头戏：四层记忆 + PRIME 智能抽取 + hybrid 召回 + LazyDecay 衰减 + 连接图谱 + 巩固，配套 SQLite-vec / pgvector / Pinecone / Qdrant / Chroma 等向量后端——比同类框架的”向量库 KV”成熟得多（虽然 README 仍标 memory/vector “In Progress”）。
• 存储抽象极广：一个 StorageProvider 接口对接十余种后端（边缘 KV 到云数据库到多种向量库），并有 StorageMigrator，适合从本地 demo 平滑迁到生产。
• 明显短板/待确认：①核心层无多 agent 协作、无 MCP、无一等 HITL/审批（均为 roadmap Planned），需自行在客户端实现；②agentdock-core 标 private、版本 0.1.0-161-1、Status Beta，尚未作为正式 npm 包发布（README roadmap 明确”developed locally, will be published…”）；③AgentNode 构造函数里残留 console.log('AgentNode Constructor - Test Log...')（nodes/agent-node.ts:119）等调试代码，工程成熟度仍在打磨。

关联

• component-taxonomy · single-vs-multi-agent · multi-agent-orchestration
• 同范式（platform / 电池齐全）：connectonion · mastra · botpress · dust · 源码：agents-example/agentdock/