DolphinX 快速上手：从配置业务 Agent 到开发自定义 Agent

假设企业已经将以下数据写入 DolphinDB：

• 设备温度、振动、电流、压力等传感器时序数据。

• 设备告警事件及其等级、发生时间和处理状态。

• 设备维护记录和维修结果。

• 设备型号、所属产线等基础信息。

我们希望 Agent 能回答这类问题：

• 过去 24 小时哪些设备温度异常？

• 3 号产线最近一周的振动指标是否持续升高？

• 帮我生成今天的设备运行日报。

• 这次异常更像传感器故障，还是设备真实劣化？

这个 Agent 的任务边界是：基于当前数据分析设备状态、解释异常依据并给出排查建议。它不能脱离实际查询结果编造设备状态，也不应在数据不足时给出确定性故障结论。

使用具备管理权限的账号登录 DolphinX Web 管控台，新建一个 Agent。

建议填写以下基本信息：

• 名称：设备运行分析助手

• 描述：面向设备运维人员，分析设备时序数据、告警记录和维护记录，识别异常趋势并生成运行日报

• 使用范围：设备运维团队

创建完成后，后续的 Prompt、模型、Skill、MCP 和权限都围绕这个 Agent 配置。

系统 Prompt 需要明确角色、数据依据、回答结构和安全边界。可以使用下面的内容作为初始版本：

你是设备运行分析助手，面向工业设备运维人员工作。

你可以基于 DolphinDB 中的设备传感器数据、告警记录和维护记录，
帮助用户分析设备状态、异常趋势和可能原因。

回答时遵循以下原则：
1. 先给出结论，再说明数据依据。
2. 涉及设备状态和数值判断时，优先通过已绑定的 DolphinDB 工具查询当前数据，不要凭经验编造数值。
3. 对异常设备，尽量说明异常指标、影响设备、时间范围和建议排查方向。
4. 区分已经由数据证实的事实、基于现象作出的推测和仍需验证的假设。
5. 如果数据不足以支撑判断，明确说明缺少哪些数据以及下一步应如何验证。
6. 不执行未经授权的数据修改、删除或设备控制操作。

首次配置时不要把全部领域知识都写入 Prompt。Prompt 主要规定 Agent 的稳定身份和行为边界；具体分析方法、日报模板和业务规则更适合放入 Skill。

设备运行分析通常包含一批稳定、可复用的方法。建议至少准备以下两个 Skill。

Agent 必须能够查询当前数据，才能回答实时状态、历史趋势和告警记录相关问题。如果企业已经通过 DolphinDB MCP 暴露查询能力（DolphinDB 可以作为 MCP Server，参见MCP 工具开发指南 ），可以在 DolphinX 中配置相应的 MCP Server，并绑定到当前 Agent。

建议将工具设计成含义清晰、输入受约束的业务接口。例如：

工具应尽量表达业务动作，而不是直接向模型暴露一个不受限制的通用脚本执行入口。还要确保工具使用当前用户身份或受控服务身份访问 DolphinDB，使数据访问继续受到既有权限体系约束。

为 Agent 绑定合适的默认模型；如果业务需要，也可以配置备用模型。随后选择三类问题进行测试：

1. 单次查询：帮我看一下 3 号产线过去 24 小时有没有异常设备。

2. 趋势分析：最近一周振动持续升高的设备有哪些？

3. 综合输出：生成今天的设备运行日报。

测试时重点检查：

• Agent 是否在需要数据时调用了正确工具。

• 查询的设备范围和时间范围是否准确。

• 结论中的数值能否从工具结果中找到依据。

• 需要分析方法或日报格式时，是否加载了正确 Skill。

• 数据不足时，Agent 是否主动说明限制，而不是补造结论。

当回答效果不符合预期时，不要只修改 Prompt。使用 context.preview 查看本轮实际组装的上下文，依次检查：

• 系统 Prompt 是否为最新版本。

• 目标 Skill 是否可见并已加载。

• MCP 工具定义是否注入，名称和参数说明是否清晰。

• 是否召回了无关记忆。

• 历史摘要是否遗漏了当前任务所需信息。

• 各部分是否占用过多 Token，导致关键材料没有进入上下文。

context.preview 只返回上下文预览，不调用模型，也不推进会话，适合在正式测试前排查配置问题。

完成调试后，将 Agent 授权给设备运维人员。正式发布前，建议使用一组固定问题验收，并记录期望行为。

至此，一个通过 Web 配置的业务 Agent 就基本完成了。它的核心并不是编写一段冗长的 Prompt，而是根据业务需求，对 Prompt、Skill、MCP 等组件进行合理、受控的组合与配置。。

在 API 集成路径中，DolphinX 不取代原有业务系统。比较清晰的职责划分如下。

这个边界能够让投研平台继续掌握业务流程和工具执行，DolphinX 则承担可复用的 Agent Runtime 能力。

一次研报复现任务可以按以下顺序推进：

1. 投研平台创建复现任务，并为该任务创建一个 DolphinX session。

2. 平台解析研报，提取因子公式、数据字段、股票池、回测区间、调仓规则和关键假设。

3. 平台调用 chat.completions，传入用户目标和结构化外部上下文，并激活相关 Skill。

4. 模型返回复现计划、代码草稿或工具调用请求。

5. 投研平台或 MCP Server 执行工具，并将结果作为 toolResults 回填到同一个 session。

6. Agent 根据工具结果继续生成代码修改建议、复现说明和结果摘要。

7. 开发阶段使用 context.preview 检查上下文；长任务通过会话摘要保留阶段性结论。

业务系统创建复现任务时，同时调用 DolphinX 会话接口创建 session，并把返回的 sessionId 保存到任务记录中。

建议保持一项复现任务对应一个 session。后续的用户追问、模型回复、工具调用和阶段摘要都围绕这个 session 推进。这样既能保留完整任务上下文，也便于定位问题和审计调用过程。

业务侧至少需要维护以下关联信息：

研报原文通常较长，不适合每轮完整注入模型。业务系统可以先将其解析成结构化信息：

研报主题：低波动因子复现
因子定义：……
所需字段：交易日、证券代码、收盘价、复权因子……
股票池：……
回测区间：……
调仓频率：……
交易成本假设：……
待确认项：公式中的窗口边界未明确
原文证据位置：第 8 页、第 12 页

随后通过 chat.completions 的手动组装能力，将这些内容作为本轮外部上下文传给 DolphinX。调用方只需要提供业务材料和本轮控制信息，不需要自行拼接完整 Prompt；DolphinX 仍负责合并 Agent 配置、历史摘要、Skill、工具和当前输入。

组织外部上下文时建议遵循三个原则：

• 保留字段口径、公式、时间范围等会影响复现结果的精确信息。

• 对不确定或缺失的信息显式标记“待确认”，不要在解析阶段自行补全。

• 保留原文页码或段落引用，便于人工核对 Agent 的理解。

具体请求字段和 assemblyConfig 结构以当前版本的 API 列表 为准。

研报复现通常需要多项能力协同，例如：

• 研报复现方法：从自然语言和公式描述中识别复现步骤与不确定项。

• 因子开发规范：定义字段口径、缺失值处理和截面计算方式。

• Dlang 编程规范：约束 DolphinDB 脚本结构和编码风格。

• 回测插件使用规范：说明参数、结果字段和常见错误。

业务系统可以在本轮请求中显式指定需要激活的 Skill。另一种方式是将 Skill 加载接口包装成工具，让模型根据任务进度逐步加载能力。前者更确定、便于控制；后者更灵活，但需要设置清晰的工具说明和调用边界。

对于复现任务，建议在规划阶段显式激活“研报复现”Skill；只有当任务确实进入编码或回测阶段时，再加载相应的编程和工具 Skill，避免上下文过早膨胀。

模型可能在分析过程中请求以下工具：

• 查询研报字段与 DolphinDB 数据字段的映射。

• 检查现有因子库是否已有同类因子。

• 获取样本行情数据。

• 执行小范围因子计算。

• 运行回测并返回收益、回撤和换手率等结果。

chat.completions 可以接收新的用户消息，也可以接收上一轮工具调用对应的 toolResults。因此，业务系统需要实现一个工具调用循环：

• 检查模型响应中是否包含工具调用。

• 校验工具名称、参数和当前用户权限。

• 对高成本或高风险操作执行人工确认或策略校验。

• 调用业务系统内部工具，或通过 DolphinX 的 mcp.tools.call 调用 MCP 工具。

• 将工具执行状态、结果或错误作为 toolResults 回填给同一个 session。

• 继续调用 chat.completions，直到模型生成阶段性结果或任务需要人工处理。

工具结果不要只返回“成功”或“失败”。应包含模型继续判断所需的结构化信息，例如样本范围、实际参数、结果指标、警告和错误原因。对于大结果集，可以返回摘要和可进一步查询的引用，避免将完整明细一次性放进上下文。

研报复现不是一次短问答。业务系统应把模型对话状态和业务任务状态分开管理。

例如，当 Agent 提出“公式窗口边界不明确，需要用户确认”时：

• DolphinX session 保留模型为何提出这个问题的对话上下文。

• 投研平台将任务状态更新为“待确认”，并在前端展示问题。

• 用户确认后，平台把答案作为新的用户消息发送到原 session。

当 Agent 请求回测时：

• 平台将任务状态更新为“回测中”。

• 工具执行完成后，平台把回测结果作为 toolResults 回填。

• Agent 继续解释结果，并判断是否需要修改脚本或参数。

不要仅依靠聊天消息推断业务任务状态。任务重试、人工确认、执行超时和失败恢复等逻辑应由投研平台显式管理。

开发阶段可以在关键节点调用 context.preview，检查：

• 研报结构化信息是否完整进入上下文。

• 激活的 Skill 是否与当前阶段匹配。

• 工具定义是否准确，是否注入了不需要的工具。

• 历史摘要是否保留了已经确认的公式口径和回测假设。

• 大型工具结果是否挤占了其他关键材料的 token 预算。

随着任务变长，DolphinX 可以使用会话摘要承接早期历史，同时保留最近几轮原始对话。业务系统仍应把已经确认的关键参数保存在自己的任务数据中，并在需要时作为受控外部上下文传入。会话摘要适合维持对话连续性，但不应取代业务系统中的正式任务状态和参数记录。

正式接入前，至少覆盖以下测试：

完成这一步后，投研平台继续负责研报、任务、工具和界面，DolphinX 则提供会话、上下文、模型、Skill、工具结果回填和调试能力。两者通过清晰边界共同组成完整的 Agent 应用。

长期稳定的角色和安全边界写进系统 Prompt；某一类任务的处理方法、格式、示例和参考文件放入 Skill。这样便于复用和版本管理，也能减少每轮上下文体积。

先通过 context.preview 检查 Skill 是否对当前 Agent 和用户可见、Catalog 描述是否足以让模型识别其用途，以及本轮是否加载了正确 Instruction。必要时可以在业务流程的关键阶段显式激活 Skill。

需要。DolphinX 管理会话和模型上下文；业务系统仍应保存任务状态、正式参数、产物、人工确认和失败恢复信息。不要把会话历史当成业务数据库。

可以。Web 路径适合快速验证 Prompt、Skill、模型和工具设计。验证成熟后，可以继续复用这些平台配置，再由业务系统通过 API 控制会话、外部上下文和工具调用流程。