Data Agent 调试
Agent 模式通过 OpenAI Agents SDK 实现了智能体能力，为了能够打造符合用户期望、贴合公司实际情况的智能体，我们开放了智能体各个环节的提示词。系统管理员可以调整 Data Agent 的根本性的行为方式。通过修改这些指令文本，可以让 Agent 更好地理解业务场景、使用用户熟悉的术语、或者改变它回答问题的风格。
注意
指令直接影响 agent 的行为，谨慎操作
Agent 核心指令
这是 Agent 最基础的行为准则，定义了它的角色和回答风格。您可以修改让 Agent 更专注于特定业务领域（如销售分析、财务报表等），或者调整它的回答语气（更专业/更亲切），甚至添加公司特有的业务术语解释。
BI 工程师指令
这是让 Agent 成为专业 BI 工程师的核心指令，指导它如何创建和编辑可视化仪表盘。您可以在这里定义一套完整的仪表盘设计方法论，例如：不同业务场景应该选择什么图表类型（销售用柱状图、趋势用折线图）、仪表盘的布局规范（关键指标放顶部、明细数据放底部）、配色方案和视觉风格等。不同行业的可视化需求差异很大，零售业可能侧重销售漏斗和库存看板，金融业则更注重风险指标和合规报表，通过调整这些指令可以让 Agent 按照您所在行业的最佳实践来构建仪表盘。
资源搜索指令
当 Agent 搜索可用的数据集和字段时使用的附加指令。您可以指定优先搜索哪些数据集、如何处理字段别名、或者排除某些不常用的资源，帮助 Agent 更快找到与用户问题相关的数据。
值集查询指令
当 Agent 查询字段的可选值（如产品类别、地区列表等）时使用的附加指令。您可以指定优先返回哪些值、如何处理同义词（如'北京'和'首都'），或者设置返回数量限制，帮助 Agent 更精准地理解用户的筛选意图。
HQL 执行指令
Agent 执行数据查询时的附加指令。您可以在这里设置默认的数据限制条数、指定必须包含的过滤条件（如只查询最近一年数据）、或者定义特殊的数据处理规则，确保查询结果符合您的分析需求。
行业与私域指令
在这里您可以为 Agent 提供行业背景知识和公司特有的信息，帮助它更好地理解您的业务需求。您可以添加行业术语解释、公司文化介绍、常见业务流程等内容，让 Agent 在回答问题时能够结合这些背景知识，提供更贴合实际的建议和分析。
提示
此指令与 Workflow 中的 User System 指令是同一个。
创建自定义工具
Data Agent 通过“工具 (Tool)” 以插件化方式扩展能力。只要目标系统提供可访问的 HTTP/HTTPS 接口（REST、GraphQL、基于 HTTP 的 RPC 等），就可以被接入：企业内部知识库、全文 / 向量检索、内部微服务、第三方 SaaS / 平台 API、搜索引擎、RPA 服务…… 这意味着 Agent 不仅能理解并回答，还能实时“调用”你的外部/内部系统获得或写入数据，形成强大的能力边界。
工具 (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 可能没法支持。
配置步骤
- 在
设置-安全管理-API授权中，添加授权，填写名称，勾选sudo功能，记录下clientId。 - 在
模型通用配置中，开启NODE_AGENT_ENABLE参数。 - 在
模型通用配置中，配置NODE_AGENT_CLIENT_ID参数为上一步创建的clientId。