Trait ContextBackend 

pub trait ContextBackend:
    Send
    + Sync
    + Clone
    + 'static {
    type Message: ContextMessage;
    type Opts: AsRef<CommonOpts> + Clone + Send + Sync;
    type Response: Clone + Send + Sync + ContextBackendResponse;

    // Required methods
    fn user_message(&self, content: impl Into<String> + Send) -> Self::Message;
    fn system_message(&self, content: impl Into<String> + Send) -> Self::Message;
    fn tool_message(
        &self,
        tool_call_id: impl Into<String> + Send,
        content: impl Into<String> + Send,
    ) -> Self::Message;
    fn merge_chunks(
        &self,
        responses: &[Self::Response],
    ) -> Option<Self::Message>;
    fn extract_messages(
        &self,
        responses: &[Self::Response],
    ) -> Result<Vec<Self::Message>, AgentError>;
    fn estimate_tokens(
        &self,
        messages: &[Self::Message],
    ) -> impl Future<Output = Result<usize, AgentError>> + Send;
    fn send(
        &self,
        messages: &[Self::Message],
        opts: &Self::Opts,
    ) -> impl Future<Output = Result<Self::Response, AgentError>> + Send;
    fn send_stream(
        &self,
        messages: Vec<Self::Message>,
        opts: Self::Opts,
    ) -> impl Stream<Item = Result<Self::Response, AgentError>> + Send + 'static;

    // Provided methods
    fn to_system_message(&self, msg: Self::Message) -> Self::Message { ... }
    fn to_request_messages(
        &self,
        messages: Vec<Self::Message>,
    ) -> Result<Vec<Self::Message>, AgentError> { ... }
    fn classify_chunk(
        &self,
        response: &Self::Response,
        saw_thinking: &mut bool,
    ) -> Vec<StreamEvent<Self::Response>> { ... }
    fn message_to_json(&self, msg: &Self::Message) -> Result<String, AgentError> { ... }
    fn message_from_json(&self, line: &str) -> Result<Self::Message, AgentError> { ... }
}

后端 trait：抽象 LLM 后端的完整接口。

实现此 trait 即可让 AgentContext 对接任意 LLM 后端（DeepSeek、智谱、OpenAI 等）。

方法分类

类别	方法	类型
消息工厂	user_message、system_message、tool_message	实例方法
格式转换	to_system_message、to_request_messages	实例方法（默认实现）
响应解析	extract_messages	实例方法
模型对话	estimate_tokens、send、send_stream	实例方法

Required Associated Types

type Message: ContextMessage

后端消息类型，必须实现 ContextMessage。

type Opts: AsRef<CommonOpts> + Clone + Send + Sync

后端自定义的请求选项类型，须内嵌 CommonOpts 并实现 AsRef<CommonOpts>。

典型用途：传递 model、temperature、thinking 等模型参数。

type Response: Clone + Send + Sync + ContextBackendResponse

后端完整的 API 响应类型。

• 非流式：ChatCompletion（含 choices + usage）
• 流式：ChatCompletionChunk（含 delta content / reasoning_content）

Required Methods

fn user_message(&self, content: impl Into<String> + Send) -> Self::Message

构造一条 User 角色消息。

fn system_message(&self, content: impl Into<String> + Send) -> Self::Message

构造一条 System 角色消息。

fn tool_message( &self, tool_call_id: impl Into<String> + Send, content: impl Into<String> + Send, ) -> Self::Message

构造一条 Tool 角色消息（工具调用结果）。

fn merge_chunks(&self, responses: &[Self::Response]) -> Option<Self::Message>

将流式分块合并为单条消息。

累加 content、reasoning_content、tool_calls，构造完整的 assistant 消息。 返回 None 表示分块中没有有效数据。

fn extract_messages( &self, responses: &[Self::Response], ) -> Result<Vec<Self::Message>, AgentError>

从后端非流式响应中提取消息列表。流式场景请用 merge_chunks。

fn estimate_tokens( &self, messages: &[Self::Message], ) -> impl Future<Output = Result<usize, AgentError>> + Send

估算消息列表的 token 数量。I/O 操作（可能需要调用远程 tokenizer API）。

fn send( &self, messages: &[Self::Message], opts: &Self::Opts, ) -> impl Future<Output = Result<Self::Response, AgentError>> + Send

非流式对话。发送全部消息，返回完整 Response（含 usage 等元数据）。

fn send_stream( &self, messages: Vec<Self::Message>, opts: Self::Opts, ) -> impl Stream<Item = Result<Self::Response, AgentError>> + Send + 'static

流式对话。参数为 owned（数据已移动），返回 'static 流。

Provided Methods

fn to_system_message(&self, msg: Self::Message) -> Self::Message

将消息转换为 System 角色（用于压缩摘要等场景）。

默认实现调用 ContextMessage::with_role。

fn to_request_messages( &self, messages: Vec<Self::Message>, ) -> Result<Vec<Self::Message>, AgentError>

将后端响应消息转换为请求格式。

对 !preserve_reasoning() 的消息剥离 reasoning_content，减少网络传输和 token 消耗。

默认实现调用 ContextMessage::without_reasoning。

fn classify_chunk( &self, response: &Self::Response, saw_thinking: &mut bool, ) -> Vec<StreamEvent<Self::Response>>

将流式分块分类为结构化事件，同时更新阶段状态。

默认实现基于 ContextBackendResponse::response_type 判断阶段：

• 含 reasoning_content → StreamEvent::Thinking
• 第一个 content（且之前有思维链）→ StreamEvent::ContentFirst
• 后续 content → StreamEvent::Content

fn message_to_json(&self, msg: &Self::Message) -> Result<String, AgentError>

将消息序列化为紧凑 JSON 字符串。

fn message_from_json(&self, line: &str) -> Result<Self::Message, AgentError>

从 JSON 字符串反序列化为消息。

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors