Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Agent 链式构建器 — 推荐的 Agent 创建方式。

内部收集静态工具和动态目录，build() 时组装为 ToolCatalog， 再传给 ToolUseLoop::new()。所有 setter 返回 self（不借用）， 支持流畅的链式调用。

Implementations

impl AgentBuilder

pub fn new(model: ResolvedModel) -> Self

创建构建器，绑定模型。

pub fn tool(self, reg: ToolRegistration) -> Self

注册工具。

pub fn tools( self, registrations: impl IntoIterator<Item = ToolRegistration>, ) -> Self

批量注册工具。

pub fn catalog(self, catalog: Arc<dyn ToolCatalog>) -> Self

绑定动态工具目录（MCP、插件系统等）。

可调用多次。按注册顺序，先绑定的优先级高于后绑定的。 静态工具（.tool()）永远拥有最高优先级。

示例

use std::sync::Arc;
use lellm_agent::{AgentBuilder, ToolCatalog};
use lellm_mcp::{McpCatalog, McpClient};

let client = Arc::new(McpClient::with_transport(transport));
let catalog = McpCatalog::discover(client).await?;
let agent = AgentBuilder::new(model)
    .catalog(Arc::new(catalog))
    .build();

pub fn max_iterations(self, max: usize) -> Self

设置最大迭代轮次（默认 10）。

pub fn max_output_tokens(self, max: u32) -> Self

设置每次 LLM 请求的最大输出 token 数（默认 4k）。

pub fn max_total_output_tokens(self, max: u32) -> Self

设置整个 Agent Run 的最大输出 token 总数。

pub fn system(self, system: impl Into<Prompt>) -> Self

设置系统提示。

支持简单文本或分层 Prompt（通过 From<String> 自动转换）。

示例

// 简单文本
let agent = AgentBuilder::new(model)
    .system("你是一个有帮助的助手。")
    .build();

// 分层构建 — 最大化前缀缓存
use lellm_core::Prompt;
let agent = AgentBuilder::new(model)
    .system(
        Prompt::builder()
            .layer_cached("核心身份…")
            .layer_cached("工具指南…")
            .layer_dynamic("会话上下文…")
            .build(),
    )
    .build();

pub fn system_prompt(self, prompt: String) -> Self

👎Deprecated since 0.5.0:

Use .system() instead

设置系统提示（纯文本）。

这是 .system() 的别名，保留用于向后兼容。

pub fn tool_cache_policy(self, policy: ToolCachePolicy) -> Self

设置工具缓存策略（默认 Auto）。

• Auto：为未设置 cache_control 的工具自动添加 Breakpoint
• Preserve：不修改用户设置的 cache_control
• Disabled：清除所有工具的 cache_control

pub fn request_options(self, opts: RequestOptions) -> Self

设置完整的 RequestOptions（覆盖所有生成参数）。

pub fn temperature(self, t: f64) -> Self

设置生成温度（0.0 ~ 2.0）。

pub fn top_p(self, p: f64) -> Self

设置 nucleus sampling 阈值（0.0 ~ 1.0）。

pub fn seed(self, s: u64) -> Self

设置随机种子，保证可复现性。

pub fn tool_choice(self, choice: ToolChoice) -> Self

设置工具选择策略（仅首轮生效）。

pub fn stop_sequences(self, seqs: Vec<String>) -> Self

设置停止序列。

pub fn prefill(self, text: String) -> Self

设置预填充文本（引导模型输出方向）。

pub fn reasoning(self, r: ReasoningConfig) -> Self

设置推理配置（控制模型是否进行深度推理）。

pub fn stream_thinking(self, enable: bool) -> Self

设置是否流式输出推理过程。

pub fn reasoning_budget(self, max: u32) -> Self

设置单轮推理 Token 上限。

pub fn max_total_reasoning_tokens(self, max: u32) -> Self

设置整个 Agent Run 的最大推理 Token 总数。

pub fn fallback(self, fallback: Arc<dyn FallbackStrategy>) -> Self

设置 Fallback 策略。

pub fn retry_policy(self, policy: RetryPolicy) -> Self

设置工具重试策略。

pub fn context_budget(self, budget: ContextBudget) -> Self

设置上下文预算（Token 上限 + 压缩策略）。 若要关闭限制，设置 max_tokens = usize::MAX。

pub fn build(self) -> ToolUseLoop

构建 ToolUseLoop。

将静态工具和动态目录坍缩为最终的 ToolCatalog， 传给 ToolUseLoop::new()。