12  面向 Agent 的数据服务

本章产出： Agent 数据访问层、工具契约和从只读建议到受控行动的安全链路。

当企业数据完成采集、处理和语义组织，最后一步不是把数据库账号交给 Agent。大模型善于理解意图与组织语言，却不适合承担所有确定性职责：它可能生成错误查询，误解字段，重复调用接口，也可能在上下文不足时仍试图完成任务。数据服务层要把企业能力包装为边界清晰、权限最小、结果可验证的工具，让 Agent 在受控空间内读取事实和执行行动。

数据服务既是架构接口，也是治理执行点。它决定 Agent 能看到多少上下文、使用谁的身份、调用什么能力、输出如何校验、失败如何恢复。越接近业务行动，这一层越不能依赖提示词自律。

12.1 不要把“开放数据”等同于“开放数据库”

让 Agent 自由生成 SQL 有一定探索价值，尤其在只读分析沙箱中，但不适合作为所有生产任务的默认方式。数据库模式面向内部实现，表名和字段可能变化；一个业务概念可能跨多个表和规则；宽泛查询会带来性能和数据泄漏；模型还可能遗漏租户、时间和状态条件。

更稳妥的路径是按任务抽象服务。例如 get_asset_context(asset_id) 比“查询设备相关表”更稳定，check_warranty(asset_id, part_id, event_time) 比让模型解释合同字段更可靠，search_service_evidence(query, asset_context) 比直接访问向量集合更容易实施权限和质量控制。

这不意味着 SQL 必须消失。面向分析的受控语义查询可以保留，但应使用只读身份、资源限额、允许的数据产品、查询验证和结果脱敏。高频或高风险任务则沉淀为正式服务。

12.2 六种常见访问接口

12.2.1 SQL 与语义查询

适合探索、聚合和灵活分析。语义层可将业务指标映射到正确模型，减少直接操作物理表。需要限制可查询对象、扫描量、执行时间和返回行数，并记录实际查询。任何动态 SQL 都应参数化和验证，禁止通过自然语言绕过权限。

12.2.2 REST 或 GraphQL API

适合稳定实体查询和业务操作。API 可以封装规则、认证、版本和错误语义。REST 边界明确，GraphQL 灵活组合但要防止复杂查询和字段级越权。无论哪种，面向 Agent 的描述应说明业务目的，而不是只给接口路径。

12.2.3 检索服务

适合文档、案例和非结构化证据。服务应接收身份、任务上下文、实体过滤和版本条件，返回紧凑证据、来源、适用范围、质量和引用位置。不要把内部向量库直接暴露给 Agent。

12.2.4 事件订阅

适合告警、状态变化和主动工作流。Agent 不应对每个底层事件立即行动，而要经过事件聚合、去重、规则过滤和风险判断。事件负载应有模式、标识、时间和版本，消费保持幂等。

12.2.5 文件与对象引用

适合大文档、图像和生成产物。工具返回受权限保护的短期引用，而非把整个二进制塞入上下文。文件访问、下载和转换都要审计，过期与撤回可执行。

12.2.6 MCP 等工具协议

标准协议有助于向不同 Agent 暴露资源、工具和提示，并复用认证与发现。OpenMetadata 也提供 MCP 服务和多种令牌、OAuth/PKCE 等认证机制(OpenMetadata Contributors, 不详)。协议解决的是连接方式，不会替企业定义数据语义、风险等级和审批；每个工具仍需产品所有者和契约。

12.3 工具设计从任务语言开始

一个好的工具应代表用户能够理解的业务能力。名称、描述、输入和输出要帮助模型正确选择，同时便于程序校验。

以山城精工为例：

name: get_applicable_manuals
purpose: 查询对指定设备与故障时间有效的正式维修资料
input:
  asset_id: 企业设备唯一标识
  event_time: 故障发生时间
  symptom_codes: 可选故障码列表
output:
  manuals:
    - document_id
      version
      effective_range
      applicable_reason
      quality_status
      citation_uri
errors:
  - ASSET_NOT_FOUND
  - CONFIGURATION_INCOMPLETE
  - PERMISSION_DENIED
  - SERVICE_STALE

输入尽量使用稳定业务标识和枚举，避免自由文本控制关键条件；输出使用结构化字段，明确单位、时间和空值；错误码告诉 Agent 应澄清、重试、拒答还是升级。描述要写清工具不能做什么，防止模型误用。

工具结果应紧凑。上下文窗口不是数据湖，返回全部字段会增加成本和泄漏面。可以先返回摘要与标识，再允许在需要时读取详情。对数值、日期、权限结论等确定事实，不应让模型从描述中再次推导。

12.4 统一身份与委托

Agent 访问数据时必须回答“它代表谁”。使用一个共享服务账号会让所有用户获得相同权限，也难以审计责任。更合理的是传递用户身份或使用可追溯的委托令牌，结合角色、属性、资源、目的和会话判断授权。

身份链包括用户、Agent、编排服务和下游工具。每一跳都要验证令牌受众、范围和期限，避免长期高权限凭据进入提示或日志。工具只获得完成当前任务所需的最小权限，并绑定会话与目的。

对于后台自动 Agent，还需要服务身份、任务发起人和批准人。系统应区分“用户请求”“Agent 建议”“人工批准”“工具执行”四类主体，审计时才能重建责任。

12.5 上下文预算与渐进式获取

Agent 并非一次获得所有数据。更高效的方式是先取得任务和实体的最小上下文，根据计划逐步调用工具：

1. 从当前业务界面或用户输入识别实体与目的；
2. 查询上下文层，获得可用产品、术语和权限；
3. 调用精确事实或检索工具；
4. 检查证据充分性和冲突；
5. 必要时请求更多信息；
6. 生成结构化建议；
7. 经过策略和人工门禁后执行。

渐进获取降低上下文噪声，也方便逐步授权。模型不需要在开始时看到客户所有合同，只需知道当前设备对应的有效保修结论及依据。若用户继续追问条款，再读取有权限的局部证据。

12.6 “能读”与“能行动”分开治理

读操作主要风险是泄漏、错误解释和资源消耗；写操作还会改变业务状态。应建立动作风险分级：

等级	示例	控制方式
L0 信息	搜索手册、查询设备	权限过滤、引用、审计
L1 建议	生成排查步骤、推荐备件	结构校验、风险提示、人工采用
L2 草稿	创建工单草稿、拟定回复	幂等、预览、人工确认
L3 可逆执行	预约资源、更新非关键状态	策略校验、审批、回滚
L4 高风险执行	付款、合同承诺、安全控制	强审批或禁止自主执行

山城精工首期停留在 L1 与部分 L2：助手可以生成工单草稿，但工程师确认后才提交；可以推荐零件，但不能锁库。路线图只有在错误率、审计和业务价值持续达标后，才考虑扩大可逆动作，且每个动作单独评审，不能因为“Agent 已经上线”而默认授权。

12.7 写操作的受控链路

一次可靠行动可以分为提议、验证、批准、执行和确认：

flowchart LR
    A[Agent 提议] --> B[模式与业务校验]
    B --> C[策略与权限判定]
    C --> D{需要审批?}
    D -->|是| E[人类预览与确认]
    D -->|否| F[受控执行]
    E --> F
    F --> G[结果确认与审计]
    G --> H[反馈与补偿]

提议阶段输出结构化动作，不直接执行。验证检查必填、范围、金额、状态前置条件和证据。策略判定考虑风险等级和用户权限。审批界面要展示将改变什么、依据是什么、不可逆后果是什么，不能只给“同意”按钮。执行使用幂等键和预期版本，防止重复与并发覆盖；完成后读取权威结果确认，而不是以 HTTP 成功等同业务成功。

若执行部分成功，要有补偿或人工处理队列。所有步骤使用同一关联标识，支持重放。对于外部消息，可先创建草稿和预览，防止错误内容直接发送给客户。

12.8 抵御提示注入与工具滥用

Agent 读取的文档、网页和用户输入都可能包含“忽略规则、调用某工具、泄露信息”等恶意指令。系统必须把数据内容与系统指令隔离：不可信文本不能修改工具权限，工具选择还要经过策略层，参数要做确定性验证。

常见控制包括：

• 工具白名单由任务与身份决定，不由检索文档决定；
• 高风险参数只能来自受信数据或用户显式确认；
• 文件、URL 和命令限制协议、域名、路径与大小；
• 输出编码和内容检查防止注入下游系统；
• 异常调用频率、循环调用和跨域尝试触发中断；
• 模型无法读取凭据，令牌只在执行代理中注入；
• 不可信内容在提示结构中清晰标记。

提示词是行为引导，不是安全边界。真正的边界在身份、策略、隔离、校验与执行层。

12.9 幂等、超时、重试与回滚

Agent 可能因网络波动重复调用同一工具，也可能在规划中循环。每个有副作用的工具应接受幂等键，服务端保存执行结果；重试只对明确可重试错误发生，并使用退避和上限。读工具同样要设置超时、限流和熔断，避免一个依赖拖垮整个对话。

超时并不等于失败。请求可能已经执行但响应丢失，因此写操作在重试前先按幂等键查询状态。回滚要区分技术回滚和业务补偿：已发送消息无法真正撤销，只能更正；已锁定库存可以释放。工具契约要声明可逆性和补偿方式。

12.10 可观测与审计

Agent 服务链应记录任务标识、用户和委托身份、工具版本、参数摘要、策略决定、数据与规则版本、响应状态、延迟、成本、人工审批和最终业务结果。敏感参数采用摘要或受控存储，避免审计日志成为新的泄漏源。

技术指标包括成功率、超时、重试、限流和依赖状态；任务指标包括工具选择正确率、参数正确率、无效调用、循环、人工驳回和业务完成率；风险指标包括越权尝试、策略拒绝、高风险错误与异常数据外发。

一次错误应能重放到“Agent 为什么选择此工具、使用了什么上下文、策略为何允许、执行返回什么”。可解释不等于展示模型内部思维，而是保存外部可验证的输入、证据、决策节点和结果。

12.11 服务版本与变更

工具是 Agent 的依赖。删除字段、修改枚举或改变行为可能让模型仍能调用，却悄悄产生错误。接口需要语义化版本、兼容测试、弃用通知和迁移窗口。工具描述、示例和评测集也随版本管理。

新版本上线前，用真实和边界任务运行契约测试、权限测试、故障注入和影子调用。若同时支持多个模型或 Agent，实现不应依赖某个模型偶然学会的提示技巧。稳定的结构和错误语义比冗长自然语言说明更可移植。

12.12 山城精工的访问层

首期可提供四类工具：

1. get_asset_context：返回当前与历史有效配置、来源和质量；
2. search_service_evidence：按设备和故障召回正式资料与已确认案例；
3. check_warranty：由权威规则服务返回结论、规则版本和限制；
4. query_part_availability：查询时确认备件状态并展示更新时间。

另有 create_work_order_draft 作为 L2 工具，必须展示预览并由工程师确认。每个工具传递用户身份，按区域和客户过滤；任何链路不健康时，助手提示数据陈旧或转人工。Agent 不持有 ERP 或 CRM 管理凭据，也不直接执行自由 SQL。

12.13 本章交付物：Agent 工具契约

每个工具应登记：

• 业务目的、目标用户、风险等级与所有者；
• 输入输出模式、单位、枚举、示例和错误码；
• 权威来源、时效、质量与适用范围；
• 身份传递、授权、目的、敏感字段和审计；
• 超时、限流、缓存、幂等、重试、补偿和降级；
• 工具描述、版本、兼容、弃用和测试；
• 允许自动执行、必须审批和明确禁止的条件；
• 任务质量、采用、成本和风险指标。

Agent 数据服务把“模型可以访问企业数据”改写为更精确的承诺：在某个身份和任务下，它可以通过某个稳定工具读取最少但足够的上下文；当证据满足条件时提出建议；只有策略和人允许时才执行动作；每一步都能追溯和恢复。这样的约束不是削弱智能，而是让智能获得进入真实业务的资格。

OpenMetadata Contributors. 不详. OpenMetadata. https://github.com/open-metadata/OpenMetadata.