Data Agent 调试

Agent 模式通过 OpenAI Agents SDK 实现了智能体能力，为了能够打造符合用户期望、贴合公司实际情况的智能体，我们开放了智能体各个环节的提示词。系统管理员可以调整 Data Agent 的根本性的行为方式。通过修改这些指令文本，可以让 Agent 更好地理解业务场景、使用用户熟悉的术语、或者改变它回答问题的风格。

注意

指令直接影响 agent 的行为，谨慎操作

默认的资源搜索、值集查询和 HQL 执行指令要求在证据足够时停止探索；未命中时只做有明确依据的补查，不把有限样本当成全表缺失。已保存的自定义指令保持不变。行业与私域指令与 Workflow 共用，升级不会自动覆盖已有内容，调整前应保留公司的业务规则。

Agent 核心指令

这是 Agent 最基础的行为准则，定义了它的角色和回答风格。您可以修改让 Agent 更专注于特定业务领域（如销售分析、财务报表等），或者调整它的回答语气（更专业/更亲切），甚至添加公司特有的业务术语解释。

BI 工程师指令

这是让 Agent 成为专业 BI 工程师的核心指令，指导它如何创建和编辑可视化仪表盘。您可以在这里定义一套完整的仪表盘设计方法论，例如：不同业务场景应该选择什么图表类型（销售用柱状图、趋势用折线图）、仪表盘的布局规范（关键指标放顶部、明细数据放底部）、配色方案和视觉风格等。不同行业的可视化需求差异很大，零售业可能侧重销售漏斗和库存看板，金融业则更注重风险指标和合规报表，通过调整这些指令可以让 Agent 按照您所在行业的最佳实践来构建仪表盘。

资源搜索指令

当 Agent 搜索可用的数据集和字段时使用的附加指令。您可以指定优先搜索哪些数据集、如何处理字段别名、或者排除某些不常用的资源，帮助 Agent 更快找到与用户问题相关的数据。

值集查询指令

当 Agent 查询字段的可选值（如产品类别、地区列表等）时使用的附加指令。您可以指定优先返回哪些值、如何处理同义词（如'北京'和'首都'），或者设置返回数量限制，帮助 Agent 更精准地理解用户的筛选意图。

HQL 执行指令

Agent 执行数据查询时的附加指令。您可以在这里设置默认的数据限制条数、指定必须包含的过滤条件（如只查询最近一年数据）、或者定义特殊的数据处理规则，确保查询结果符合您的分析需求。

行业与私域指令

在这里您可以为 Agent 提供行业背景知识和公司特有的信息，帮助它更好地理解您的业务需求。您可以添加行业术语解释、公司文化介绍、常见业务流程等内容，让 Agent 在回答问题时能够结合这些背景知识，提供更贴合实际的建议和分析。

提示

此指令与 Workflow 中的 User System 指令是同一个。

分析模板

在 Agent 调优页面中，除了各类 Agent 指令，还可以通过 分析模板 标签页管理分析模板。分析模板适合沉淀可重复使用的提问骨架，例如销售分析、经营复盘、区域对比等常见场景。

分析模板的作用

系统管理员在 分析模板 中统一维护模板标题、模板内容、启用状态。
终端用户在 ChatBI / Data Agent 的 Agent 模式下可以直接点击模板卡片，将模板内容填入输入框，再按需修改后发送。
Workflow 模式下不展示分析模板入口。

管理行为说明

模板卡片菜单支持编辑、启用/禁用、删除。
租户启用 开关只控制租户账号登录后在 Agent 模式下是否能看到分析模板入口，不影响系统管理员在 Agent 调优页继续创建、编辑、启用/禁用或删除模板。
页面内新建模板仍然保留 20 条上限控制；达到上限后，“创建分析模板”按钮会被禁用。
PROMPT_TEMPLATES 配置在读取和保存时都会按更新时间倒序规范化到最多 20 条；如果通过接口写入了超过 20 条模板，系统会在后续读取/编辑时自动裁剪到前 20 条，避免展示与删除行为不一致。

使用建议

标题建议直接表达分析意图，例如“销售额趋势分析”“区域经营对比”。
模板内容建议写成可直接发送或少量改动后发送的完整问题。
对不希望继续暴露给终端用户的模板，可以先禁用，而不是直接删除。

创建自定义工具（window.heisenberg.createTool）

Data Agent 通过“工具 (Tool)” 以插件化方式扩展能力。这个能力由全局 JS 注入的 window.heisenberg.createTool() Hook 提供，入口位于“系统设置 → 全局 JS”的 Data Agent 页签。只要目标系统提供可访问的 HTTP/HTTPS 接口（REST、GraphQL、基于 HTTP 的 RPC 等），就可以被接入：企业内部知识库、全文 / 向量检索、内部微服务、第三方 SaaS / 平台 API、搜索引擎、RPA 服务…… 这意味着 Agent 不仅能理解并回答，还能实时“调用”你的外部/内部系统获得或写入数据，形成强大的能力边界。

如果你还需要查看全局 JS 中其它可直接使用的 Hook（例如 window.customI18nPostProcessor），可一并参考全局 JS 设置。

什么时候应该创建自定义 Tool

如果你的目标是“让 Agent 知道平台外的信息，或替你完成一个动作”，就应该考虑创建自定义 Tool。常见场景包括：

补知识：接企业知识库、内部 FAQ、制度文档，让 Agent 能回答租户私有知识。
补实时数据：接订单、库存、工单、审批状态等业务 API，让回答基于实时数据，而不是只靠模型记忆。
补动作能力：让 Agent 创建工单、发起审批、写回备注、触发业务流程。
补外部检索：接搜索引擎、向量检索、外部 SaaS API，扩展 Agent 的可用信息源。

如果你只是想改欢迎语、提示文案、按钮文字，或者隐藏某个页面元素，不需要创建 Tool；那属于全局 CSS / 全局 JS 的定制范围。

工具 (Tool) 参数定义

字段	必填	说明
name	是	默认为函数名（例如 get_weather）。
include	否	正则表达式数组，表示此工具只在符合条件的页面提供
exclude	否	正则表达式数组，表示此工具只在符合条件的页面不提供
description	是	提供给 LLM 的清晰、可读的人类描述。
parameters	是	可以是 Zod schema 或原始 JSON schema 对象。使用 Zod 参数会自动启用 strict 模式。
execute	是	(args, context) => string

示例：将 Agent 与企业知识库、外部 API 等打通

下面以接入 Tavily Web Search 为例，演示如何在“系统设置 → 全局 JS”中注册一个搜索类 Tool：

// 确认 Agent 运行环境已注入 createTool
if (typeof window.heisenberg?.createTool === 'function') {
  const apiKey = '<tavily_api_key>'; // 建议使用代理服务管理功能，而不是直接写死
  window.heisenberg.createTool({
    // 工具名称：英文 + 下划线，便于 LLM 可靠指称
    name: 'web_search',
    // 工具用途：帮助模型判断何时调用
    description: '使用 Tavily 搜索最新的互联网信息，并返回答案与来源',
    // 参数：完全可按需扩展 —— 任何你希望 LLM 生成 / 传入的控制项都可以放进来
    parameters: window.heisenberg.zod.object({
      plan: window.heisenberg.zod.string().describe('你调用该工具的目的与关键信息摘录'),
      query: window.heisenberg.zod.string().describe('搜索内容/查询关键词'),
      max_results: window.heisenberg.zod.number().min(1).max(20).default(5).describe('需要的结果条数'),
      // 可继续添加如 language、time_range、site、freshness 等参数
    }),
    // 具体执行逻辑：只要能发起 HTTP 请求即可集成（fetch / axios / 自建 SDK 均可）
    execute: async (args) => {
      try {
        const { query, max_results } = args;
        const resp = await fetch('https://api.tavily.com/search', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${apiKey}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            query,
            max_results,
            search_depth: 'basic',
            include_answer: true,
            include_raw_content: true,
            include_images: false,
            time_range: null,
          }),
        });
        const data = await resp.json().catch(() => ({}));
        if (!resp.ok) {
          return `搜索失败：${data?.error || resp.status} ${resp.statusText}`;
        }
        return `搜索结果：\n\n${data.answer || '（无直接答案）'}\n\n来源：\n${JSON.stringify(data.results || [], null, 2)}`;
      } catch (err) {
        return `搜索时出现错误：${err?.message || String(err)}`;
      }
    },
  });
}

保存并刷新后，Data Agent 即可通过该 Tool 搜索互联网。以此类推：只要目标能力能够通过 HTTP 请求访问，就可以封装成一个 Tool 并被 Agent 动态调用，快速扩展到企业内部系统或任意第三方服务。

通用接入建议：

身份与安全：优先采用代理服务管理，避免直接在全局 JS 中明文暴露 token。
返回格式：将原始响应提炼为简洁文本或结构化 JSON，再拼接成字符串返回，减少无关噪音。
最小权限：服务端实施鉴权、IP/速率限制与访问审计，防止滥用。
参数设计：让 LLM 只暴露必要、可控的参数，减少越权或无效调用。

提示

你可以注册多个 Tool（搜索、知识库检索、报表生成、流程触发、工单创建……），Agent 会在推理链中自主选择并组合调用，形成持续可演进的“能力面”。
通过全局 JS 拓展的工具目前只能在网页端使用，无法在 Agent API 模式下使用。

如何在 AI API 中使用 Agent 模式？

API 调用默认使用 Workflow 模式，如果需要使用 Agent 模式，需要有额外的环境要求，并进行额外配置。

环境要求

Node JS 22 及以上版本，需要在衡石服务所在机器上安装 Node JS 环境，确保衡石服务可以调用。比较老的系统比如 CentOS7 可能没法支持。
需要 Node 全局安装 tsx，npm install -g tsx。

配置步骤

在设置-安全管理-API授权中，添加授权，填写名称，勾选 sudo 功能，记录下 clientId。
在模型通用配置中，开启 NODE_AGENT_ENABLE 参数。
在模型通用配置中，配置 NODE_AGENT_CLIENT_ID 参数为上一步创建的 clientId。

手工安装 Node.js（VM、Docker、K8s）

本节适用于 HENGSHI SENSE 6.2 的 Linux 部署。Node.js 和全局安装的 tsx 必须在运行衡石后端服务的环境中可用；容器部署只在宿主机上安装无效。多节点部署需要覆盖所有运行衡石后端服务的节点或副本。

准备安装包

从 Node.js 官方下载目录下载 22 及以上版本的 Linux 二进制包，并按对应版本的 SHASUMS256.txt 校验文件。以下以 v24.18.0、linux-x64 为例：

text

https://nodejs.org/dist/v24.18.0/node-v24.18.0-linux-x64.tar.xz

解压环境需要具备 tar 和 xz 解压工具。若提示找不到 xz，请先通过操作系统包管理器安装相应工具，再执行解压命令。

在目标 VM 或容器内执行 uname -m 确认架构：x86_64 选择 linux-x64，aarch64 选择 linux-arm64，并同步替换后续命令中的包名和目录名。容器内的操作系统和系统库也必须满足该 Node.js 版本的要求；遇到 GLIBC 版本错误时，应先使用兼容的系统或容器镜像。

安装 tsx 的环境需要能访问 npm 仓库。离线环境应先在相同操作系统、CPU 架构的联网环境中完成 Node.js 解压和 tsx 安装，再整体传入安装目录，保留软链接及执行权限；只复制 tsx 可执行文件或只下载 Node.js 安装包不够。

VM 部署

以衡石运行用户执行操作，确保该用户可以写入安装目录。示例将 Node.js 放在 /opt/hsdata，衡石安装在 /opt/hengshi；请按实际路径调整。

上传安装包到 /opt/hsdata，解压并安装 tsx：

shell

cd /opt/hsdata
tar -xJf node-v24.18.0-linux-x64.tar.xz
export PATH=/opt/hsdata/node-v24.18.0-linux-x64/bin:$PATH
npm install -g --prefix /opt/hsdata/node-v24.18.0-linux-x64 tsx
node --version
npm --version
tsx --version

在 /opt/hengshi/conf/hengshi-sense-env.sh 中加入以下配置，让服务启动时也能找到 Node.js、npm、npx 和 tsx：
shell
```
export PATH=/opt/hsdata/node-v24.18.0-linux-x64/bin:$PATH
```
1

重启衡石服务，使新进程继承 PATH：

shell

cd /opt/hengshi
bin/hengshi-sense-bin restart hengshi

只修改登录用户的 .bashrc 或在当前终端执行 export PATH=...，不能保证服务进程使用新的环境。集群部署请在每个衡石后端服务节点重复安装、配置和重启操作。

Docker 部署

以下基于 6.2 容器部署的 Docker Compose 配置，服务名为 hengshi，容器名为 hengshi-sense。安装目录 /opt/hsdata 必须已有持久化挂载，避免重建容器后丢失 Node.js 和 tsx。

将安装包复制到容器并进入容器：

shell

docker cp node-v24.18.0-linux-x64.tar.xz hengshi-sense:/opt/hsdata/
docker exec -it hengshi-sense /bin/bash

在容器内解压并安装 tsx，确保衡石运行用户有读取和执行权限：

shell

cd /opt/hsdata
tar -xJf node-v24.18.0-linux-x64.tar.xz
export PATH=/opt/hsdata/node-v24.18.0-linux-x64/bin:$PATH
npm install -g --prefix /opt/hsdata/node-v24.18.0-linux-x64 tsx
node --version
tsx --version
exit

在宿主机查看容器原有 PATH：
shell
```
docker exec hengshi-sense printenv PATH
```
1
编辑部署目录的 .env，在原有 PATH 前加上 Node.js 的 bin 目录，并保留原有路径。例如，原 PATH 为 /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 时加入：
dotenv
```
PATH=/opt/hsdata/node-v24.18.0-linux-x64/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
```
1
6.2 部署包通过 env_file: .env 将变量传入容器。自定义 Compose 配置也必须将 PATH 传给 hengshi 服务。不要在 .env 中直接写 :$PATH，以免被替换成宿主机的 PATH。

在部署目录重建衡石容器并验证：

shell

docker-compose up -d --no-deps --force-recreate hengshi
docker exec hengshi-sense node --version
docker exec hengshi-sense npm --version
docker exec hengshi-sense npx --version
docker exec hengshi-sense tsx --version

docker restart 或 docker-compose restart 不会加载修改后的容器环境变量。使用 Compose V2 时，将命令中的 docker-compose 替换为 docker compose。

K8s 部署

衡石支持通过 ReadWriteMany（RWX）PVC 在多个后端副本之间共享安装目录。K8s 部署的 hengshi.yaml 已提供被注释的共享存储示例，包括 hengshi-ext-api-data、hengshi-geo-data 及对应的 volumes、volumeMounts。由于各客户集群的 StorageClass 不同，需要先按实际环境配置，再取消对应配置的注释。

以下参考该模板，为 Node.js 配置独立的共享 PVC hengshi-node-data，挂载到每个衡石服务容器的 /opt/hengshi-node-data。Node.js 和 tsx 在共享目录中安装一次，Pod 重建后继续使用同一 PVC 中的安装文件。共享该安装目录的 Pod 必须使用相同的 CPU 架构和兼容的系统库。示例 namespace 为 hengshi，Deployment 为 hengshi-sense，衡石容器为 hengshi-sense-ins；自定义部署请替换为实际名称。

参考 hengshi.yaml 中被注释的 PVC 模板，启用一组 Node.js 共享存储配置。将 storageClassName 替换为集群中支持 ReadWriteMany 的 StorageClass，并按需调整容量。原模板中的 longhorn 是示例值，不能直接作为所有环境的配置：
yaml
```
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: hengshi-node-data
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: <RWX_STORAGE_CLASS>
  resources:
    requests:
      storage: 2Gi
```
1
2
3
4
5
6
7
8
9
10
11
将该 PVC 作为独立 YAML 文档保存在 hengshi.yaml 中，与 Deployment 之间保留 --- 分隔符。

参考原文件中被注释的挂载配置，在 Deployment 的 spec.template.spec.volumes 中增加：

yaml

- name: hengshi-node
  persistentVolumeClaim:
    claimName: hengshi-node-data

在 hengshi-sense-ins 容器的 volumeMounts 中增加以下内容，保留已有挂载和容器配置：

yaml

- name: hengshi-node
  mountPath: /opt/hengshi-node-data

应用配置，确认 PVC 为 Bound、各副本已挂载共享目录后再安装：

shell

kubectl -n hengshi apply -f hengshi.yaml
kubectl -n hengshi get pvc hengshi-node-data
kubectl -n hengshi rollout status deployment/hengshi-sense
kubectl -n hengshi get pods -l hsapp=hengshi-sense,hsrole=hengshi

选择一个已挂载 PVC 的 Pod，将安装包复制到共享目录并进入容器。将 <Pod名称> 替换为实际值：
shell
```
kubectl -n hengshi cp node-v24.18.0-linux-x64.tar.xz <Pod名称>:/opt/hengshi-node-data/ -c hengshi-sense-ins
kubectl -n hengshi exec -it <Pod名称> -c hengshi-sense-ins -- /bin/bash
```
1
2
在容器内解压并安装 tsx：
shell
```
cd /opt/hengshi-node-data
tar -xJf node-v24.18.0-linux-x64.tar.xz
export PATH=/opt/hengshi-node-data/node-v24.18.0-linux-x64/bin:$PATH
npm install -g --prefix /opt/hengshi-node-data/node-v24.18.0-linux-x64 tsx
node --version
tsx --version
exit
```
1
2
3
4
5
6
7
只在一个 Pod 中执行安装，避免多个副本同时修改同一安装目录。安装用户需要共享目录的写权限，各 Pod 的衡石运行用户需要读取和执行权限；共享存储应保留软链接并允许执行文件。离线环境按“准备安装包”中的方法，将已安装 tsx 的完整 Node.js 目录复制到 PVC 的挂载目录中。
查看衡石容器原有 PATH：
shell
```
kubectl -n hengshi exec <Pod名称> -c hengshi-sense-ins -- printenv PATH
```
1
在 hengshi.yaml 的 hengshi-sense-ins 容器中配置 env，在原 PATH 前加上 Node.js 的 bin 目录。例如，原 PATH 为 /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 时，加入或更新以下条目，并保留其他环境变量：
yaml
```
env:
  - name: PATH
    value: /opt/hengshi-node-data/node-v24.18.0-linux-x64/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
```
1
2
3
PATH 必须填写容器的完整实际路径，不能直接写 :$PATH。仅在安装终端执行 export PATH=... 不会更新已经运行的衡石服务进程。重新应用 Deployment，使所有副本通过新建 Pod 加载 PATH：
shell
```
kubectl -n hengshi apply -f hengshi.yaml
kubectl -n hengshi rollout status deployment/hengshi-sense
kubectl -n hengshi get pods -l hsapp=hengshi-sense,hsrole=hengshi
```
1
2
3
Helm 管理的部署应将 PVC、挂载和 PATH 配置保存在对应 chart / values 中，并通过原有升级流程应用，避免后续发布覆盖配置。

对每个新 Pod 验证工具可用，确认重建后的 Pod 仍可读取 PVC 中的安装文件：

shell

kubectl -n hengshi exec <Pod名称> -c hengshi-sense-ins -- node --version
kubectl -n hengshi exec <Pod名称> -c hengshi-sense-ins -- npm --version
kubectl -n hengshi exec <Pod名称> -c hengshi-sense-ins -- npx --version
kubectl -n hengshi exec <Pod名称> -c hengshi-sense-ins -- tsx --version

验证 Agent API

确认 Node.js 版本至少为 22，且 npm、npx、tsx 均可执行后，按本页的“配置步骤”完成 API 授权及模型配置，再发起一次 Agent 模式的 AI API 请求验证。若出现找不到 node、npx 或 tsx 的错误，检查衡石服务启动时继承的 PATH、安装目录权限，以及容器重建后安装文件是否仍存在。

用户手册

ChatBot

命令参考

数据集成

数据填报

创建数据集

数据集加工

函数列表

仪表盘创作

图表类控件

图表高级计算

功能类控件

展示类控件

应用设置

Data Agent

模型供应商

Data Agent 调试 ​

Agent 核心指令 ​

BI 工程师指令 ​

资源搜索指令 ​

值集查询指令 ​

HQL 执行指令 ​

行业与私域指令 ​

分析模板 ​

分析模板的作用 ​

管理行为说明 ​

使用建议 ​

创建自定义工具（window.heisenberg.createTool） ​

什么时候应该创建自定义 Tool ​

工具 (Tool) 参数定义 ​

示例：将 Agent 与企业知识库、外部 API 等打通 ​

如何在 AI API 中使用 Agent 模式？ ​

环境要求 ​

配置步骤 ​

手工安装 Node.js（VM、Docker、K8s） ​

准备安装包 ​

VM 部署 ​

Docker 部署 ​

K8s 部署 ​

验证 Agent API ​

Data Agent 调试

Agent 核心指令

BI 工程师指令

资源搜索指令

值集查询指令

HQL 执行指令

行业与私域指令

分析模板

分析模板的作用

管理行为说明

使用建议

创建自定义工具（window.heisenberg.createTool）

什么时候应该创建自定义 Tool

工具 (Tool) 参数定义

示例：将 Agent 与企业知识库、外部 API 等打通

如何在 AI API 中使用 Agent 模式？

环境要求

配置步骤

手工安装 Node.js（VM、Docker、K8s）

准备安装包

VM 部署

Docker 部署

K8s 部署

验证 Agent API