AI 问数 API 怎么设计？给业务系统和 Agent 调用时要注意什么

AI 问数最容易被看见的形态，是一个聊天框。

但企业真正落地后，问数能力不会只给人用。

业务系统要调用它。

经营看板要调用它。

自动化 Agent 要调用它。

飞书、企业微信、钉钉里的机器人也要调用它。

所以，AI 问数最终需要成为一层可调用的数据分析 API。

一，API 不能只接收问题文本

一个最简单的接口可能是：

传入问题，返回答案。

但企业场景远不够。

接口还需要知道：

• •谁在问；
• •代表哪个组织或项目；
• •当前角色有什么权限；
• •使用哪个语义版本；
• •是否允许返回明细；
• •答案要给人看，还是给另一个 Agent 使用。

没有这些上下文，API 很容易变成无权限边界的文本转 SQL 服务。

二，身份和权限必须透传

当业务系统调用 AI 问数 API 时，不能统一用系统账号代替所有用户。

否则系统无法判断当前用户能看哪些数据。

更合理的方式是透传用户身份、角色和数据范围，让问数层继承企业权限。

三，语义版本要可控

企业的指标口径、字段说明和业务规则会变化。

如果 API 每次使用的语义版本不可见，业务系统就很难解释为什么同一个问题前后答案不同。

AI 问数 API 应该能记录本次回答使用了哪个数据源、语义配置和指标版本。

四，复杂查询要支持异步

不是所有问题都能 5 秒返回。

秒级指标查询可以同步返回。

深度归因、跨表分析、长报告生成可能需要异步任务。

API 设计时要区分快速问数和深度分析，避免所有问题都走同一种路径。

五，错误要可解释

API 不应该只返回“失败”。

它应该能说明失败原因：

• •没有权限；
• •找不到合适数据源；
• •问题太模糊；
• •查询超时；
• •指标口径缺失；
• •数据质量不足。

这样业务系统和 Agent 才能继续引导用户补充信息。

六，要保留审计和追溯

Snowflake Cortex Analyst 官方文档把自然语言数据问答能力提供为 REST API。

Databricks Genie 也提供 Genie Agents API，但官方文档提醒，在调用会话 API 前，应先准备好经过整理的 Genie Agent，否则即使 API 集成正确，用户也可能得到错误结果。

这说明 API 只是调用方式，真正决定可靠性的仍然是语义、权限和质量管理。

AskTable 的 API 视角

AskTable 可以作为人和业务 Agent 共用的数据问答能力。

对人，它是自然语言问数入口。

对系统和 Agent，它是可被调用的数据分析能力。

BuildTable 提供数据基础和语义模型。

AskTable 在 API 调用时处理身份、权限、指标口径、查询过程和答案解释。

结论

AI 问数 API 不能只设计成“问题进、答案出”。

企业真正需要的是一个带身份、权限、语义版本、异步任务、错误解释和审计能力的数据分析接口。

只有这样，问数能力才能从聊天框扩展到业务系统、协作工具和 Agent 工作流。

参考来源

• •Snowflake：Cortex Analyst REST API
• •Databricks：Use the Genie Agents API
• •Microsoft Fabric：Fabric Data Agent Python SDK