lellm_agent/tools/
mod.rs

1//! 工具系统 — Agent Runtime 的组成部分。
2//!
3//! 提供 ToolRegistry, ToolExecutor, ToolUseLoop 以及防御机制
4//! （循环检测、重试策略、Fallback 等）。
5
6pub mod executor;
7pub mod fallback;
8pub mod loop_detector;
9pub mod registry;
10pub mod retry;
11pub mod runtime;
12pub mod signal_voter;
13
14pub use executor::{ParallelSafety, ToolCategory, ToolExecutor, ToolRegistration};
15pub use fallback::{
16    DefaultFallback, FallbackAction, FallbackContext, FallbackReason, FallbackStrategy,
17};
18pub use lellm_provider::ResolvedModel;
19pub use loop_detector::{LoopDetector, LoopIntervention};
20pub use registry::{ToolRegistry, ToolSearchResult, ToolSource};
21pub use retry::{BackoffStrategy, RetryPolicy, ToolErrorKind};
22pub use runtime::{ToolCallResult, ToolUseLoop, ToolUseResult};
23pub use signal_voter::{NegativeSignal, SignalVoter};
24
25/// Agent 层流式事件 — 封闭、强类型、exhaustive match
26///
27/// 终态契约：
28/// - 正常结束：`LoopEnd` 恰好一次，然后 channel 关闭
29/// - 异常结束：`LoopError` 恰好一次，然后 channel 关闭
30/// - 终态事件后不再发送任何事件
31#[derive(Debug)]
32pub enum AgentEvent {
33    /// Provider 层事件
34    Provider(lellm_provider::ProviderEvent),
35    /// 工具开始执行
36    ToolStart { tool_call_id: String, name: String },
37    /// 工具执行完成
38    ToolEnd {
39        tool_call_id: String,
40        result: ToolCallResult,
41    },
42    /// 工具重试
43    Retry {
44        tool_call_id: String,
45        attempt: usize,
46        max_attempts: usize,
47        reason: String,
48    },
49    /// Agent loop 正常结束（恰好一次，后不再发送）
50    LoopEnd { result: ToolUseResult },
51    /// Agent loop 异常结束（恰好一次，后不再发送）
52    LoopError {
53        error: lellm_core::LlmError,
54        iterations: usize,
55        messages: Vec<lellm_core::Message>,
56    },
57}
58
59/// Agent loop 停止原因 — 描述"为什么停止"，而非"响应长什么样"
60#[derive(Debug, Clone, PartialEq, Eq)]
61pub enum StopReason {
62    /// Agent 已获得最终答案并正常结束
63    Complete,
64    /// 达到最大轮次
65    MaxIterationsReached,
66    /// 检测到循环
67    LoopDetected,
68    /// Fallback 主动给出最终结果
69    FallbackComplete,
70}
71
72/// Agent 层流式事件通道类型别名
73pub type AgentStream = tokio::sync::mpsc::Receiver<AgentEvent>;
lellm_agent/tools/mod.rs

lellm_agent/tools/
mod.rs
