用 AI 代理构建任何东西

AgentDock 是一个用于构建复杂 AI 代理的框架，能够以可配置的确定性完成复杂任务。它由两个主要组件组成：

1. AgentDock Core：一个开源、后端优先的框架，用于构建和部署 AI 代理。它设计为与框架无关且与供应商无关，使您能够完全控制代理的实现。

2. 开源客户端：一个完整的 Next.js 应用程序，作为 AgentDock Core 框架的参考实现和消费者。您可以在 https://hub.agentdock.ai 上查看其实际运行效果。

AgentDock 使用 TypeScript 构建，强调简单性、可扩展性和可配置的确定性，使其成为构建可靠且可预测的 AI 系统的理想选择，这些系统可以在最少监督的情况下运行。

🌐 AgentDock Pro 即将推出：通过我们全面的云平台体验 AI 自动化的未来，该平台配备可视化工作流构建器、高级编排功能和企业级基础设施。请在 AgentDock.ai 注册，以获得抢先体验资格，并在我们上线时赢取免费平台积分。

📖 AI 代理书籍：通过我们的综合指南，掌握构建生产级 AI 代理的完整方法论——从基础知识到企业级部署模式，尽在 AI 代理书籍。

🎯 全面的提示库：我们正在构建最广泛的提示库，涵盖日常自动化需求和高度专业化的垂直领域要求。从通用生产力工具到行业特定的工作流，我们精心挑选的提示集合可为任何场景下的代理提供经过实战检验的提示。

演示

格雷戈里·豪斯医生： 一个诊断推理引擎，可在多阶段工作流中协调使用**search、deep_research** 和 pubmed 工具，运用与专家诊断医师相媲美的严谨调查技术来解决复杂的医疗病例。

https://github.com/user-attachments/assets/50c766dc-fc65-481c-aad2-9a71169c7b28

认知推理器： 一个多阶段推理引擎，可在可配置的工作流中协调七种专门的认知工具（search、think、reflect、compare、critique、brainstorm、debate），以类似人类的推理模式系统地分解并解决复杂问题。

https://github.com/user-attachments/assets/279a4e48-a980-4f83-becb-5e039fe10c56

历史导师： 一个沉浸式教育代理，结合向量化的历史知识与**search** 功能以及动态的 Mermaid 图表渲染，可按需创建真实的 learning 体验，直观展示复杂的历史关系和时间线。

https://github.com/user-attachments/assets/56e80a15-eac3-452b-aa8b-efe7b7f3360c

卡路里视觉： 一个基于视觉的营养分析系统，结合计算机视觉与结构化数据提取技术，可以从食物图像中精确分析宏量和微量营养素的构成，如同一位营养师般无需手动输入即可即时量化餐食成分。

https://github.com/user-attachments/assets/6b4e71cf-accc-4c18-bb42-7bc5ad2f37e4

🌐 README 翻译

Français • 日本語 • 한국어 • 中文 • Español • Deutsch • Italiano • Nederlands • Polski • Türkçe • Українська • Ελληνικά • Русский • العربية

🧠 设计原则

AgentDock 基于以下核心原则构建：

• 简单至上：只需最少的代码即可创建功能性代理
• 节点式架构：所有能力均以节点形式实现
• 工具即专用节点：工具扩展了节点系统，以支持代理的能力
• 可配置的确定性：控制代理行为的可预测性
• 类型安全：全程采用全面的 TypeScript 类型定义

可配置的确定性

可配置的确定性 是 AgentDock 设计理念的核心，它使您能够在创意型 AI 能力与可预测的系统行为之间取得平衡：

• AgentNode 本身具有非确定性，因为 LLM 每次都可能生成不同的响应。
• 通过定义工具执行路径，可以使工作流更具确定性。
• 开发者可以通过配置系统中哪些部分使用 LLM 推理来控制确定性的程度。
• 即使包含 LLM 组件，通过结构化的工具交互，整个系统的运行行为仍然保持可预测性。
• 这种平衡的方法使您的 AI 应用既具备创造力，又拥有可靠性。

确定性工作流

AgentDock 完全支持您在典型工作流构建器中熟悉的确定性工作流。无论是否使用 LLM 推理，您所期望的可预测执行路径和可靠结果都能实现：

flowchart LR
  Input[输入] --> Process[处理]
  Process --> Database[(数据库)]
  Process --> Output[输出]
  
  style Input fill:#f9f9f9,stroke:#333,stroke-width:1px
  style Output fill:#f9f9f9,stroke:#333,stroke-width:1px
  style Process fill:#d4f1f9,stroke:#333,stroke-width:1px
  style Database fill:#e8e8e8,stroke:#333,stroke-width:1px

非确定性代理行为

借助 AgentDock，当您需要更高的适应性时，也可以利用带有 LLM 的 AgentNode。根据需求，其创造性输出可能会有所不同，同时仍能保持结构化的交互模式：

flowchart TD
  Input[用户查询] --> Agent[AgentNode]
  Agent -->|"LLM 推理（非确定性）"| ToolChoice{工具选择}
  ToolChoice -->|"选项 A"| ToolA[深度研究工具]
  ToolChoice -->|"选项 B"| ToolB[数据分析工具]
  ToolChoice -->|"选项 C"| ToolC[直接响应]
  ToolA --> Response[最终响应]
  ToolB --> Response
  ToolC --> Response
  
  style Input fill:#f9f9f9,stroke:#333,stroke-width:1px
  style Agent fill:#ffdfba,stroke:#333,stroke-width:1px
  style ToolChoice fill:#ffdfba,stroke:#333,stroke-width:1px
  style ToolA fill:#d4f1f9,stroke:#333,stroke-width:1px
  style ToolB fill:#d4f1f9,stroke:#333,stroke-width:1px
  style ToolC fill:#d4f1f9,stroke:#333,stroke-width:1px
  style Response fill:#f9f9f9,stroke:#333,stroke-width:1px

具有确定性子工作流的非确定性代理

AgentDock 通过将非确定性代理智能与确定性工作流执行相结合，为您提供两全其美的解决方案：

flowchart TD
  Input[用户查询] --> Agent[AgentNode]
  Agent -->|"LLM 推理（非确定性）"| FlowChoice{子工作流选择}
  FlowChoice -->|"决策 A"| Flow1[确定性工作流 1]
  FlowChoice -->|"决策 B"| Flow2[确定性工作流 2]
  FlowChoice -->|"决策 C"| DirectResponse[生成响应]
  
  Flow1 --> |"步骤 1 → 2 → 3 → ... → 200"| Flow1Result[工作流 1 结果]
  Flow2 --> |"步骤 1 → 2 → 3 → ... → 100"| Flow2Result[工作流 2 结果]
  
  Flow1Result --> Response[最终响应]
  Flow2Result --> Response
  DirectResponse --> Response
  
  style Input fill:#f9f9f9,stroke:#333,stroke-width:1px
  style Agent fill:#ffdfba,stroke:#333,stroke-width:1px
  style FlowChoice fill:#ffdfba,stroke:#333,stroke-width:1px
  style Flow1 fill:#c9e4ca,stroke:#333,stroke-width:1px
  style Flow2 fill:#c9e4ca,stroke:#333,stroke-width:1px
  style Flow1Result fill:#c9e4ca,stroke:#333,stroke-width:1px
  style Flow2Result fill:#c9e4ca,stroke:#333,stroke-width:1px
  style DirectResponse fill:#ffdfba,stroke:#333,stroke-width:1px
  style Response fill:#f9f9f9,stroke:#333,stroke-width:1px

这种方法允许由智能代理决策调用复杂的多步骤工作流（可能涉及数百个在工具中实现或作为连接节点序列的确定性步骤）。尽管这些工作流是由非确定性代理推理触发的，但它们的执行过程仍然是可预测的。

对于更高级的 AI 代理工作流和多阶段处理管道，我们正在构建 AgentDock Pro——一个功能强大的平台，用于创建、可视化和运行复杂的代理系统。

可配置确定性的简要说明

可以把它想象成开车：有时你需要 AI 的创造力（比如在城市街道上导航——非确定性），而有时则需要可靠、循序渐进的流程（比如按照高速公路指示牌行驶——确定性）。AgentDock 让你能够构建同时运用这两种方式的系统，在任务的每个环节选择合适的方法。这样，你既能获得 AI 的智慧，又能在需要时得到可预测的结果。

🏗️ 核心架构

该框架基于一个功能强大、模块化的节点系统构建，作为所有代理功能的基础。这种架构使用不同的节点类型作为构建块：

• BaseNode：基础类，为所有节点建立核心接口和能力。
• AgentNode：一种专门的核心节点，负责编排 LLM 交互、工具使用和代理逻辑。
• 工具与自定义节点：开发者可通过扩展 BaseNode 的节点来实现代理能力和自定义逻辑。

这些节点通过受管注册表进行交互，并可通过核心架构的端口及潜在的消息总线相互连接，从而实现复杂、可配置且可能具有确定性的代理行为和工作流。

有关节点系统组件和功能的详细说明，请参阅节点系统文档。

🚀 开始使用

有关全面指南，请参阅入门指南。

需求

• Node.js ≥ 20.11.0 (LTS)
• pnpm ≥ 9.15.0（必需）
• LLM 提供商的 API 密钥（Anthropic、OpenAI 等）

安装

1. 克隆仓库：

   git clone https://github.com/AgentDock/AgentDock.git
   cd AgentDock
   

2. 安装 pnpm：

   corepack enable
   corepack prepare pnpm@latest --activate
   

3. 安装依赖项：

   pnpm install
   

   如果需要从头开始重新安装：

   pnpm run clean-install
   

   此脚本会移除所有 node_modules 和锁文件，并正确地重新安装依赖项。

4. 配置环境：

   基于 .env.example 创建环境文件（.env 或 .env.local）：

   # 选项 1：创建 .env.local
   cp .env.example .env.local
   
   # 选项 2：创建 .env
   cp .env.example .env
   

   然后将您的 API 密钥添加到环境文件中。

5. 启动开发服务器：

   pnpm dev
   

部署开源客户端

点击上方按钮，即可将 AgentDock 开源客户端直接部署到您的 Vercel 账户。

高级功能

功能	描述	文档
会话管理	对话的隔离且高效的会话状态管理	会话文档
编排框架	根据上下文控制智能体行为和工具可用性	编排文档
存储抽象层	具有可插拔提供者的灵活存储系统，支持键值存储、向量存储和安全存储	存储文档
评估框架	使用多样化的评估器系统地衡量并提升智能体质量	评估文档

目前，存储系统正在演进中，已支持键值存储（包括内存、Redis 和 Vercel KV 提供者）以及客户端安全存储；同时，向量存储和其他后端也在开发中。

📕 文档

AgentDock 框架的文档可在 hub.agentdock.ai/docs 以及本仓库的 /docs/ 目录下找到。文档内容包括：

• 入门指南
• API 参考
• 节点创建教程
• 集成示例

如需更全面的生态文档和指南，请访问 agentdock.ai/docs。

📂 仓库结构

本仓库包含以下内容：

1. AgentDock 核心库：位于 agentdock-core/ 目录下的核心框架。
2. 开源客户端：基于 Next.js 构建的完整参考实现，作为 AgentDock 核心框架的消费者。
3. 示例智能体：位于 agents/ 目录中的即用型智能体配置。
4. AI 智能体手册：位于 content/ai-agents-book/ 目录下的综合指南内容。

您可以独立在自己的应用中使用 AgentDock 核心库，也可以将本仓库作为起点来构建您自己的智能体驱动的应用程序。

📝 智能体模板

AgentDock 包含多个预配置的智能体模板。您可以在 agents/ 目录中探索这些模板，或阅读 智能体模板文档，以了解详细的配置信息。

🔧 示例实现

示例实现展示了特定的使用场景和高级功能：

实现	描述	状态
编排型智能体	利用编排机制根据上下文调整行为的示例智能体	已可用
认知推理器	使用结构化推理和认知工具解决复杂问题	已可用
智能体规划器	专门用于设计和实现其他 AI 智能体的智能体	已可用
代码游乐场	具有丰富可视化能力的沙箱式代码生成与执行环境	计划中

🔐 环境配置详情

AgentDock 开源客户端需要 LLM 提供商的 API 密钥才能正常运行。这些密钥需在环境文件（.env 或 .env.local）中进行配置，您可以基于提供的 .env.example 文件创建该文件。

LLM 提供商 API 密钥

请添加您的 LLM 提供商 API 密钥（至少需要一个）：

# LLM 提供商 API 密钥 - 至少需要一个
ANTHROPIC_API_KEY=sk-ant-xxxxxxx  # Anthropic API 密钥
OPENAI_API_KEY=sk-xxxxxxx         # OpenAI API 密钥
GEMINI_API_KEY=xxxxxxx            # Google Gemini API 密钥
DEEPSEEK_API_KEY=xxxxxxx          # DeepSeek API 密钥
GROQ_API_KEY=xxxxxxx              # Groq API 密钥

API 密钥解析顺序

AgentDock 开源客户端在解析使用哪个 API 密钥时，遵循以下优先级顺序：

1. 每个智能体自定义的 API 密钥（通过 UI 中的智能体设置进行配置）
2. 全局设置中的 API 密钥（通过 UI 中的设置页面进行配置）
3. 环境变量（来自 .env.local 文件或部署平台）

工具专用 API 密钥

部分工具也需要各自的 API 密钥：

# 工具专用 API 密钥
SERPER_API_KEY=                  # 搜索功能所需
FIRECRAWL_API_KEY=               # 更深层网页搜索所需

有关环境配置的更多详细信息，请参阅 src/types/env.ts 中的实现。

使用您自己的 API 密钥 (BYOK)

AgentDock 采用 BYOK（自带密钥）模式：

1. 在应用程序的设置页面中添加您的 API 密钥。
2. 或者，您也可以通过请求头直接传递密钥以供 API 使用。
3. 密钥将使用内置加密系统安全存储。
4. 我们不会共享或存储任何 API 密钥。

📦 包管理工具

该项目要求使用 pnpm 进行一致的依赖管理。npm 和 yarn 不受支持。

💡 您可以构建的内容

1. AI 驱动的应用程序

   • 自定义聊天机器人，搭配任意前端
   • 命令行 AI 助手
   • 自动化数据处理流水线
   • 后端服务集成

2. 集成能力

   • 支持任何 AI 提供商（OpenAI、Anthropic 等）
   • 适用于任何前端框架
   • 可对接任何后端服务
   • 自定义数据源和 API

3. 自动化系统

   • 数据处理工作流
   • 文档分析流水线
   • 自动化报告系统
   • 任务自动化智能体

核心特性

特性	描述
🔌 框架无关（Node.js 后端）	核心库可与 Node.js 后端栈集成。
🧩 模块化设计	由简单节点构建复杂系统
🛠️ 可扩展	可为任何功能创建自定义节点
🔒 安全	内置 API 密钥和数据的安全特性
🔑 BYOK	使用您自己的 API 密钥 调用 LLM 提供商
📦 自包含	核心框架依赖项极少
⚙️ 多步工具调用	支持复杂推理链
📊 结构化日志记录	提供对代理执行的详细洞察
🛡️ 健壮的错误处理	行为可预测，调试更简化
📝 TypeScript 优先	类型安全，提升开发者体验
🌐 开源客户端	包含完整的 Next.js 参考实现
🔄 编排	基于上下文对代理行为进行动态控制
💾 会话管理	并发对话之间的隔离状态
🎮 可配置的确定性	通过节点逻辑/工作流平衡 AI 的创造性和可预测性
📊 评估框架	强大的工具用于定义、运行和分析代理性能评估

🧰 组件

AgentDock 的模块化架构基于以下关键组件：

• BaseNode: 系统中所有节点的基础
• AgentNode: 代理功能的主要抽象
• 工具与自定义节点: 以节点形式实现的可调用能力和自定义逻辑。
• 节点注册表: 管理所有节点类型的注册与检索
• 工具注册表: 管理代理可用的工具
• CoreLLM: 与 LLM 提供商交互的统一接口
• 提供商注册表: 管理 LLM 提供商的配置
• 评估框架: 代理评估的核心组件
• 错误处理: 用于处理错误并确保行为可预测的系统
• 日志记录: 用于监控和调试的结构化日志系统
• 编排: 根据对话上下文控制工具的可用性和行为
• 会话: 管理并发对话之间的状态隔离

有关这些组件的详细技术文档，请参阅 架构概述。

🗺️ 路线图

以下是 AgentDock 的开发路线图。此处列出的大多数改进都与核心 AgentDock 框架 (agentdock-core) 相关，该框架目前在本地开发中，待达到稳定版本后将作为版本化的 NPM 包发布。部分路线图项目也可能涉及对开源客户端实现的增强。

功能	描述	类别
存储抽象层	具有可插拔提供者的灵活存储系统	进行中
高级记忆系统	长期上下文管理	进行中
向量存储集成	基于嵌入的文档和记忆检索	进行中
AI 代理评估	全面的测试和评估框架	进行中
平台集成	支持 Telegram、WhatsApp 等消息平台	计划中
多代理协作	使代理能够协同工作	计划中
模型上下文协议 (MCP) 集成	支持通过 MCP 发现和使用外部工具	计划中
语音 AI 代理	通过 AgentNode 使用语音界面和电话号码的 AI 代理	计划中
遥测与可追溯性	高级日志记录和性能跟踪	计划中
工作流运行时与节点	复杂自动化的核心运行时、节点类型和编排逻辑	计划中
AgentDock Pro	用于扩展 AI 代理和工作流的全面企业云平台	云
自然语言 AI 代理构建器	可视化构建器 + 自然语言代理和工作流构建	云
代理市场	可盈利的代理模板	云

👥 贡献

我们欢迎对 AgentDock 的贡献！请参阅 CONTRIBUTING.md 获取详细的贡献指南。

📜 许可证

AgentDock 采用 MIT 许可证 发布。

✨ 构建任何东西！

AgentDock 提供了构建您所能想象的几乎任何 AI 驱动的应用程序或自动化的基础。我们鼓励您探索该框架，构建创新的代理，并为社区做出贡献。让我们共同构建 AI 交互的未来吧！

AgentDock 快速上手指南

AgentDock 是一个用于构建复杂 AI 智能体（AI Agents）的开源框架，主打可配置的确定性。它允许开发者在利用大模型创造力的同时，通过结构化工作流确保系统行为的可预测性。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Windows, macOS 或 Linux
• Node.js: 版本 ≥ 20.11.0 (推荐使用 LTS 版本)
• 包管理器: pnpm ≥ 9.15.0 (必须)
• API 密钥: 准备好大模型提供商的 API Key（如 OpenAI, Anthropic 等）

提示：国内开发者若遇到 npm/pnpm 源连接缓慢的问题，建议配置国内镜像源（如腾讯云或阿里云镜像）以加速依赖下载。

安装步骤

1. 克隆项目仓库

git clone https://github.com/AgentDock/AgentDock.git
cd AgentDock

2. 安装并激活 pnpm

AgentDock 强制要求使用 pnpm。如果您尚未安装，请使用以下命令启用 Corepack 并激活最新版的 pnpm：

corepack enable
corepack prepare pnpm@latest --activate

3. 安装项目依赖

在项目根目录下运行：

pnpm install

4. 配置环境变量

复制示例环境变量文件并根据需要修改（填入您的 LLM API Key）：

cp .env.example .env

编辑 .env 文件，填入您的密钥，例如：

OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key

基本使用

AgentDock 的核心架构基于**节点（Node）**系统。所有功能（包括工具和工作流）都被实现为节点。

核心概念

• BaseNode: 所有节点的基础类。
• AgentNode: 专门用于编排 LLM 交互、工具调用和智能体逻辑的核心节点。
• Tools: 作为特殊节点扩展，赋予智能体具体能力（如搜索、计算、数据库查询）。

运行示例智能体

项目内置了多个演示智能体，您可以直接运行它们来体验框架功能。

示例：运行 "Dr. Gregory House" (医疗诊断推理智能体)

该智能体展示了如何编排 search、deep_research 和 pubmed 工具来处理复杂的医疗案例。

pnpm run agent:dr-house

示例：运行 "Cognitive Reasoner" (认知推理引擎)

该智能体展示了多阶段推理，协调 think、reflect、critique 等七个专用认知工具。

pnpm run agent:cognitive-reasoner

开发自定义智能体

要构建自己的智能体，您需要创建继承自 BaseNode 的新节点，并在主程序中通过 AgentNode 进行编排。

1. 在 agents 目录下创建新文件夹。
2. 定义您的工具节点（实现特定逻辑）。
3. 配置 AgentNode 的工作流，决定何时调用 LLM（非确定性）以及何时执行固定脚本（确定性）。

更多详细开发文档请参考官方文档：https://hub.agentdock.ai/docs