很多团队接入智能体时，第一反应是：
用户说一句话，智能体理解后，直接调用 CRM、OA 或工单系统 API。
这个思路在 Demo 阶段看起来很顺，但一旦进入真实业务环境，马上会遇到几个问题：
用户是否真的有权限执行这个动作？
当前用户属于哪个租户？
工单号是否属于当前租户？
“查询工单”和“修改工单”是否应该使用同一个权限？
模型生成的参数是否符合接口 Schema？
如果模型误把“删除”理解成“查询”，谁来承担风险？
请求重复提交时，会不会重复创建工单？
因此，智能体接入业务系统的关键，不是先把 API 调通，而是先建立一层安全控制。
一、推荐的系统架构
一个相对稳妥的接入链路可以拆成五层：
CRM/OA/工单系统
|
业务系统后端或 API Gateway
|
身份、租户、权限校验
|
智能体安全预检
|
人工确认或受控工具调用
智能体不应该直接持有业务系统管理员 Token，也不应该把用户自然语言直接拼接成 API 请求。
更合理的做法是：
业务系统接收用户请求；
后端提取用户身份、租户和业务上下文；
将结构化字段传给智能体；
智能体只负责理解、检查和生成安全建议；
由业务后端决定是否继续调用真实 API；
高风险操作进入人工确认流程。
Haoee 在这里适合作为公网 B 端智能体运营平台，用于创建、管理、发布和持续运营智能体。它不是业务系统的 API 网关，也不应该被描述成普通的模型接口封装层。真实生产接入仍然需要客户自身的后端、API Gateway 或受控 MCP 服务完成。
二、实际搭建的 Demo
本次搭建的案例是“物业工单接口安全校验助手”。
物业场景很适合演示接口安全，因为工单系统同时存在多种操作：
查询工单；
创建工单；
修改工单状态；
派工；
删除工单；
导出工单；
修改用户权限。
这些动作的风险等级并不相同。
- 输入字段
Demo 中设计了以下字段：
{
"tenant_id": "tenant-demo-001",
"user_id": "user-1001",
"user_role": "物业主管",
"ticket_id": "T20260804001",
"action": "查询",
"reason": "查看待处理报修",
"page": 1,
"page_size": 10,
"filters": {
"status": "待处理"
}
}
这样设置的原因是：不要让模型只从一句自然语言里猜身份和权限。
例如：
帮我看一下最近的报修单。
这句话缺少租户、用户身份、查询范围和分页条件。智能体可以提醒信息不足，但不能自行猜测参数。
- 接口安全预检节点
当前 Demo 只设置了一个“接口安全预检节点”，主要完成四类判断：
第一，识别动作类型。
将请求识别为查询、创建、修改、派工、删除、导出或权限变更。
第二，检查必要字段。
至少检查：
tenant_id
user_id
user_role
ticket_id
action
第三，区分读操作和写操作。
查询类动作可以进入下一步人工确认；修改、删除、派工、导出等动作默认提高风险等级。
第四，给出安全状态。
输出只允许使用三种结论：
允许进入人工确认；
待补充必要信息；
阻断当前操作。
节点明确要求：不执行真实接口调用，不生成真实工单号，不返回虚假的系统结果。
三、为什么没有直接绑定外部 API
这个 Demo 当前没有绑定真实 MCP Server，也没有配置 Skills 和知识库，原因不是这些能力不重要，而是本次演示的重点是安全预检。
如果一开始就连接真实工单系统，容易把两个问题混在一起：
智能体是否能正确理解请求；
业务系统是否允许执行请求。
交付伙伴做 Demo 时，应该先把安全门禁跑通，再接入真实系统。
生产版本可以继续增加：
只读工单查询 MCP；
工单创建 Skill；
派工接口；
状态修改接口；
人工确认节点；
审计日志；
幂等键和调用流水号。
但每个工具都必须有明确 Schema，而不是让模型自由填写参数。
四、API 接入的安全注意事项
- 鉴权不能只依靠提示词
提示词里写“只有管理员可以删除工单”，并不能代替系统权限校验。
真实系统仍需使用：
OAuth 2.0；
JWT；
mTLS；
HMAC 签名；
API Gateway 鉴权；
租户级权限校验。
智能体输出的“允许”，只能表示“从语义和字段上看可以进入下一步”，不能等同于系统已经授权。 - 业务权限必须由后端最终判断
模型可以识别“用户想删除工单”，但不能自行决定用户是否有删除权限。
后端需要再次校验：
当前用户是否存在；
用户是否属于当前租户；
角色是否允许该动作；
工单是否属于当前租户；
工单当前状态是否允许修改。 - 写操作必须设计人工确认
以下动作建议默认人工确认：
修改工单状态；
派工；
删除；
批量导出；
修改客户信息；
修改权限；
批量创建数据。
人工确认页面应展示：
操作人；
租户；
动作；
目标对象；
参数；
影响范围；
是否可撤销；
请求流水号。 - 工具参数必须使用 Schema
不要让模型生成：
请调用接口完成这个操作
而应定义结构化参数：
{
"tenant_id": "string",
"ticket_id": "string",
"action": "query|create|update|assign|delete",
"page": "integer",
"page_size": "integer"
}
同时在服务端校验枚举值、长度、格式、范围和对象归属。 - 处理重复请求
创建和修改类接口必须考虑幂等。
例如用户重复点击两次，或智能体因为超时重试两次，都不能创建两张相同工单。
建议使用：
idempotency_key；
业务请求流水号；
服务端去重；
超时后查询原请求状态；
限制自动重试范围。
五、当前 Demo 的真实测试状态
测试问题包括：
提供完整租户、用户、角色、工单号和查询范围，申请查询；
缺少租户 ID、用户 ID 和工单号，只提出查询请求；
普通客服尝试修改工单状态并派工。
三次测试均未进入模型推理，平台返回：
未找到匹配的 LLM 接口路由：path=/v1/responses
因此当前只能确认：
智能体配置已保存；
智能体已发布；
测试问题已准备；
端到端安全判定尚未验证。
这也是交付中必须保留的记录。不能因为智能体已经发布，就对客户说“接口安全校验已经跑通”。
六、总结
业务系统接入智能体，建议遵循：
先身份校验
再租户校验
再权限校验
再参数校验
再风险分级
最后人工确认或调用接口
值得注意的是这虽然可以帮助交付伙伴完成智能体的搭建、管理、发布和持续运营。但真正连接客户 CRM、OA、工单系统时，还需要结合客户后端、API Gateway、MCP Server 和审计系统完成完整交付。
