--- url: /v6.2/agent-tune.md --- # Data Agent 调试 ![Data Agent 调试](/images/copilot/agent-tune.png) Agent 模式通过 [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/) 实现了智能体能力，为了能够打造符合用户期望、贴合公司实际情况的智能体，我们开放了智能体各个环节的提示词。系统管理员可以调整 Data Agent 的根本性的行为方式。通过修改这些指令文本，可以让 Agent 更好地理解业务场景、使用用户熟悉的术语、或者改变它回答问题的风格。 > \[!CAUTION] 注意 > 指令直接影响 agent 的行为，谨慎操作 默认的资源搜索、值集查询和 HQL 执行指令要求在证据足够时停止探索；未命中时只做有明确依据的补查，不把有限样本当成全表缺失。已保存的自定义指令保持不变。行业与私域指令与 Workflow 共用，升级不会自动覆盖已有内容，调整前应保留公司的业务规则。 ## Agent 核心指令 这是 Agent 最基础的行为准则，定义了它的角色和回答风格。您可以修改让 Agent 更专注于特定业务领域（如销售分析、财务报表等），或者调整它的回答语气（更专业/更亲切），甚至添加公司特有的业务术语解释。 ## BI 工程师指令 这是让 Agent 成为专业 BI 工程师的核心指令，指导它如何创建和编辑可视化仪表盘。您可以在这里定义一套完整的仪表盘设计方法论，例如：不同业务场景应该选择什么图表类型（销售用柱状图、趋势用折线图）、仪表盘的布局规范（关键指标放顶部、明细数据放底部）、配色方案和视觉风格等。不同行业的可视化需求差异很大，零售业可能侧重销售漏斗和库存看板，金融业则更注重风险指标和合规报表，通过调整这些指令可以让 Agent 按照您所在行业的最佳实践来构建仪表盘。 ## 资源搜索指令 当 Agent 搜索可用的数据集和字段时使用的附加指令。您可以指定优先搜索哪些数据集、如何处理字段别名、或者排除某些不常用的资源，帮助 Agent 更快找到与用户问题相关的数据。 ## 值集查询指令 当 Agent 查询字段的可选值（如产品类别、地区列表等）时使用的附加指令。您可以指定优先返回哪些值、如何处理同义词（如'北京'和'首都'），或者设置返回数量限制，帮助 Agent 更精准地理解用户的筛选意图。 ## HQL 执行指令 Agent 执行数据查询时的附加指令。您可以在这里设置默认的数据限制条数、指定必须包含的过滤条件（如只查询最近一年数据）、或者定义特殊的数据处理规则，确保查询结果符合您的分析需求。 ## 行业与私域指令 在这里您可以为 Agent 提供行业背景知识和公司特有的信息，帮助它更好地理解您的业务需求。您可以添加行业术语解释、公司文化介绍、常见业务流程等内容，让 Agent 在回答问题时能够结合这些背景知识，提供更贴合实际的建议和分析。 > \[!TIP] 提示 > 此指令与 Workflow 中的 [User System 指令](workflow-tune.md#usersystem-prompt-用户系统提示词)是同一个。 ## 分析模板 在 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 设置](global-js.md)。 ### 什么时候应该创建自定义 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 | Promise——你的业务逻辑。可选的第二个参数为 RunContext。| ### 示例：将 Agent 与企业知识库、外部 API 等打通 下面以接入 Tavily Web Search 为例，演示如何在“系统设置 → 全局 JS”中注册一个搜索类 Tool： ```js // 确认 Agent 运行环境已注入 createTool if (typeof window.heisenberg?.createTool === 'function') { const apiKey = ''; // 建议使用代理服务管理功能，而不是直接写死 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 动态调用，快速扩展到企业内部系统或任意第三方服务。 ![Agent search web](/images/copilot/ai-web-search.png) 通用接入建议： * 身份与安全：优先采用代理服务管理，避免直接在全局 JS 中明文暴露 token。 * 返回格式：将原始响应提炼为简洁文本或结构化 JSON，再拼接成字符串返回，减少无关噪音。 * 最小权限：服务端实施鉴权、IP/速率限制与访问审计，防止滥用。 * 参数设计：让 LLM 只暴露必要、可控的参数，减少越权或无效调用。 > \[!TIP] 提示 > > 1. 你可以注册多个 Tool（搜索、知识库检索、报表生成、流程触发、工单创建……），Agent 会在推理链中自主选择并组合调用，形成持续可演进的“能力面”。 > 2. 通过全局 JS 拓展的工具目前只能在网页端使用，无法在 Agent API 模式下使用。 ## 如何在 AI API 中使用 Agent 模式？ API 调用默认使用 Workflow 模式，如果需要使用 Agent 模式，需要有额外的环境要求，并进行额外配置。 ### 环境要求 1. Node JS 22 及以上版本，需要在衡石服务所在机器上安装 Node JS 环境，确保衡石服务可以调用。比较老的系统比如 CentOS7 可能没法支持。 2. 需要 Node 全局安装 tsx，`npm install -g tsx`。 ### 配置步骤 1. 在`设置-安全管理-API授权`中，添加授权，填写名称，勾选 `sudo` 功能，记录下 `clientId`。 2. 在`模型通用配置`中，开启 `NODE_AGENT_ENABLE` 参数。 3. 在`模型通用配置`中，配置 `NODE_AGENT_CLIENT_ID` 参数为上一步创建的 `clientId`。 ### 手工安装 Node.js（VM、Docker、K8s） 本节适用于 HENGSHI SENSE 6.2 的 Linux 部署。Node.js 和全局安装的 tsx 必须在**运行衡石后端服务的环境中**可用；容器部署只在宿主机上安装无效。多节点部署需要覆盖所有运行衡石后端服务的节点或副本。 #### 准备安装包 从 [Node.js 官方下载目录](https://nodejs.org/dist/) 下载 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`；请按实际路径调整。 1. 上传安装包到 `/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 ``` 2. 在 `/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 ``` 3. 重启衡石服务，使新进程继承 PATH： ```shell cd /opt/hengshi bin/hengshi-sense-bin restart hengshi ``` 只修改登录用户的 `.bashrc` 或在当前终端执行 `export PATH=...`，不能保证服务进程使用新的环境。集群部署请在每个衡石后端服务节点重复安装、配置和重启操作。 #### Docker 部署 以下基于 [6.2 容器部署](docker.md)的 Docker Compose 配置，服务名为 `hengshi`，容器名为 `hengshi-sense`。安装目录 `/opt/hsdata` 必须已有持久化挂载，避免重建容器后丢失 Node.js 和 tsx。 1. 将安装包复制到容器并进入容器： ```shell docker cp node-v24.18.0-linux-x64.tar.xz hengshi-sense:/opt/hsdata/ docker exec -it hengshi-sense /bin/bash ``` 2. 在容器内解压并安装 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 ``` 3. 在宿主机查看容器原有 PATH： ```shell docker exec hengshi-sense printenv PATH ``` 编辑部署目录的 `.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 ``` 6.2 部署包通过 `env_file: .env` 将变量传入容器。自定义 Compose 配置也必须将 PATH 传给 `hengshi` 服务。不要在 `.env` 中直接写 `:$PATH`，以免被替换成宿主机的 PATH。 4. 在部署目录重建衡石容器并验证： ```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 部署](k8s.md)的 `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`；自定义部署请替换为实际名称。 1. 参考 `hengshi.yaml` 中被注释的 PVC 模板，启用一组 Node.js 共享存储配置。将 `storageClassName` 替换为集群中**支持 ReadWriteMany** 的 StorageClass，并按需调整容量。原模板中的 `longhorn` 是示例值，不能直接作为所有环境的配置： ```yaml apiVersion: v1 kind: PersistentVolumeClaim metadata: name: hengshi-node-data spec: accessModes: - ReadWriteMany storageClassName: resources: requests: storage: 2Gi ``` 将该 PVC 作为独立 YAML 文档保存在 `hengshi.yaml` 中，与 Deployment 之间保留 `---` 分隔符。 2. 参考原文件中被注释的挂载配置，在 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 ``` 3. 选择一个已挂载 PVC 的 Pod，将安装包复制到共享目录并进入容器。将 `` 替换为实际值： ```shell kubectl -n hengshi cp node-v24.18.0-linux-x64.tar.xz :/opt/hengshi-node-data/ -c hengshi-sense-ins kubectl -n hengshi exec -it -c hengshi-sense-ins -- /bin/bash ``` 在容器内解压并安装 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 ``` 只在一个 Pod 中执行安装，避免多个副本同时修改同一安装目录。安装用户需要共享目录的写权限，各 Pod 的衡石运行用户需要读取和执行权限；共享存储应保留软链接并允许执行文件。离线环境按“准备安装包”中的方法，将已安装 tsx 的完整 Node.js 目录复制到 PVC 的挂载目录中。 4. 查看衡石容器原有 PATH： ```shell kubectl -n hengshi exec -c hengshi-sense-ins -- printenv PATH ``` 在 `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 ``` 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 ``` Helm 管理的部署应将 PVC、挂载和 PATH 配置保存在对应 chart / values 中，并通过原有升级流程应用，避免后续发布覆盖配置。 5. 对每个新 Pod 验证工具可用，确认重建后的 Pod 仍可读取 PVC 中的安装文件： ```shell kubectl -n hengshi exec -c hengshi-sense-ins -- node --version kubectl -n hengshi exec -c hengshi-sense-ins -- npm --version kubectl -n hengshi exec -c hengshi-sense-ins -- npx --version kubectl -n hengshi exec -c hengshi-sense-ins -- tsx --version ``` #### 验证 Agent API 确认 Node.js 版本至少为 22，且 npm、npx、tsx 均可执行后，按本页的“配置步骤”完成 API 授权及模型配置，再发起一次 Agent 模式的 AI API 请求验证。若出现找不到 `node`、`npx` 或 `tsx` 的错误，检查衡石服务启动时继承的 PATH、安装目录权限，以及容器重建后安装文件是否仍存在。