agent-client 业务系统接入

它解决什么

前面几关讲的是服务端。业务系统（比如订单系统）要调智能体，还得处理一堆客户端的麻烦事：流式输出、断线重连、超时重发、智能体反过来要调本地能力……agent-client 把这些封装成 SDK。

源码agent-client READMEagent-solution/common/agent-client/README.md@bf702bc9

三个标识，各归各的

业务代码只见 invocationRef，服务端的 taskId 由 SDK 内部映射。这样服务端怎么换 Task、怎么重建，都不影响业务侧。

三种调用模式

事件流是一个封闭的类型集合：受理、状态变化、增量内容、需要输入、需要确认工具调用、完成、失败等，业务可以穷尽处理。

本地工具：注册不等于暴露

智能体有时要反过来调业务系统的本地能力，比如"读当前页面""提交订单"。SDK 允许注册本地工具，但默认一个都不暴露，必须显式放行：

client.exposeInConversation("conv-1",
        ToolExposurePolicy.allow("readPage", "submitOrder"));

InvocationRequest req = InvocationRequest.gatewayBuilder("target-agent")
        .conversationId("conv-1")
        .exposure(ToolExposurePolicy.allow("readPage"))  // 本次只放行 readPage
        .build();

会话级和调用级两层策略取交集，所以调用级只能收紧、不能放大。

源码ToolExposurePolicy.andagent-solution/common/agent-client/agent-client-sdk-for-jvm/src/main/java/com/openjiuwen/client/tool/spi/ToolExposurePolicy.java:109@bf702bc9

有副作用的工具（ACTION）默认要经审批；只读的（OBSERVATION）直接执行。执行顺序是：

可见性校验 → 解析工具 → 参数校验 → 策略守卫 → （需要时）审批 → 执行 → 落库

任何一步拒绝，工具都不执行，结果以"已拒绝"续传给服务端。同一个 toolCallId 最多执行一次。

断流不等于失败

SSE 断了，SDK 按最后看到的状态判断：

恢复线索会明确告诉业务：是"稍后查询，不要重新发起"，还是"用同一幂等键原样重发"。默认重试 3 次，按 200、400、800 毫秒退避。

最后一行正好和网关那一关的幂等规则接上：只要幂等键和内容不变，重发多少次服务端都只有一个任务。

小结

• 业务只用自己的调用句柄，服务端 Task 由 SDK 映射。
• 本地工具默认不暴露，两级策略取交集；有副作用的工具默认要审批。
• 断流先查真实状态，查不清就给恢复线索，不伪造成功或失败。