ARS 第一版草稿设计（V）Tools Provider（Agent 提供者）

December 17, 2025

在前两篇中，我们已经完成了 **ChatSession / Message / SSE 和 Orchestrator 的基础实现，目前已经可以顺利的用Dummy(假接口)做成了一个可以正常交互的应用。(Orchestrator 目前还是非流式，这个可以回头再说)

这一篇开始进入 ARS 的外部适配器，Agent Provider

Agent Provider（Agent 提供者）

AgentProvider 只负责两件事：

把 AgentContext（会话、历史消息、系统提示词、参数）转换成“对外请求”
把“对外响应（流/非流）”转换成内部标准事件流

这样看下来它的职责非常清晰,也很容易理解了。

ARS · ToolsProvider 设计说明（草案）

该部分的。

1. 设计目标

AgentProvider 的设计目标如下：

平台无关：可接入 OpenAI / OpenRouter / DeepSeek / 本地模型等不同平台
Streaming-first：天然支持流式输出
内部协议稳定：对上游 RunLoop 暴露统一事件模型
职责隔离：平台差异不影响 Agent 调度与持久化逻辑
可演进：为后续 Tool Calling / 多轮 Agent Loop 预留空间

2、AgentProvider 的定位

2.1 AgentProvider 的职责

AgentProvider 是 ARS 与具体 Agent 平台之间的适配层，主要负责：

将 ARS 内部的 AgentContext 转换为平台请求格式
调用平台 API / SDK（支持 streaming）
将平台输出转换为 ARS 内部统一的事件流（AgentStream）

2.2 AgentProvider 不负责的内容

为保证边界清晰，AgentProvider 不负责：

不直接写数据库
不拼接最终 assistant 消息
不处理 Agent 决策逻辑（如是否调用工具）
不负责 Run 的终态落库

3. 整体结构设计

AgentProvider 采用接口 + 平台适配器的结构，不同平台通过 Adapter 实现接入。

flowchart TD subgraph AgentProvider I[Agent Provider Interface] subgraph PlatformAdapter[AgentPlatformAdapter] CT[ContextTransformer / RequestBuilder] AC[ApiClient] SP[StreamParser] EN[EventNormalizer] end end I -- AgentContext --> CT CT -- platform payload --> AC AC -- byte/line stream --> SP SP -- json chunks --> EN EN -- AgentStream --> AgentRunJob

Agent Provider : 我们完整的Agent提供者模块
Agent Provider Interface : 实现的抽象，定义接口层，方便不同平台接入
AgentPlatformAdapter : 不同平台的实际适配器
RequestBuilder : 将我们平台的上下文实际转换为对应平台的上下文
ApiClient : 比如像OpenAI 一类的Clinet端，也可能是其他的什么SDK
EventNormalizer: 负责把平台的输出内容转换为我们平台的结构和格式

4. 核心组件说明

Agent Provider Interface

定义统一接口，供 RunLoop 调用

interface AgentProvider {
    /** @return \Generator<ProviderEvent> */
    public function stream(AgentContext $ctx): \Generator;
}

RunLoop 只关心事件流，不关心具体平台。

ContextTransformer / RequestBuilder

负责将 ARS 内部上下文转换为平台请求结构：

会话历史 messages
system prompt
model / temperature 等参数
tools（预留）

该组件不包含任何 HTTP 或 SDK 调用逻辑。

ApiClient

负责与具体平台进行通信：

HTTP / SDK 调用
streaming 请求支持
超时与基础重试策略
网络异常处理

注意：

在开始产生流式输出后，不应自动重试请求，避免重复输出。

StreamParser

负责处理平台返回的“传输层流数据”，例如：

SSE（data: …）
chunked response
半包 / 心跳 / [DONE]

StreamParser 的输出应为结构化的 JSON chunk，不包含平台语义。

EventNormalizer

负责将平台 JSON chunk 转换为 ARS 内部标准事件：

文本增量（message.delta）
工具调用（tool.call / tool.delta，预留）
usage 信息
done / error

EventNormalizer 输出的事件是 AgentProvider 向上游暴露的唯一协议。

5. AgentStream（内部事件模型）

AgentProvider 向上游输出的是内部统一的事件流，而非平台原始响应。

message.delta
tool.call
usage
done
error

RunLoop / OutputSink / SSE 推送层仅处理这些事件。

6. 取消与可靠性约定

平台差异必须集中在 Adapter 内部
内部事件模型稳定，对外屏蔽平台细节
Streaming 作为"一等公民”
为 Tool Calling 与复杂 Agent Loop 提前预留扩展点

Tags:

ARS草稿设计