//! Agent trait —— 智能体的"角色"抽象。
//!
//! 设计要点（参见 `docs/7-agent-runtime.md` §3.2.1）：
//!
//! - **角色与会话分离**：`Agent` 定义"做什么、用什么工具"，`AgentSession` 维护"当前状态"
//! - **工具白名单扩展点**：默认从 `RuntimeBundle.tool_registry` 取全部，子 trait 可覆盖做白名单/过滤
//! - **不绑定业务循环**：`submit_turn` 在 `AgentSession` 上，不在 trait 上

use crate::agent::runtime::RuntimeBundle;
use crate::llm::types::tool::ToolDef;

/// Agent 角色抽象。
///
/// 实现此 trait 即可接入 Agent Runtime。典型实现是 struct 持有静态配置（name、system prompt 模板），
/// 也可以是基于配置动态生成的轻量实现。
pub trait Agent: Send + Sync {
    /// 角色名（用于日志、调试、UI 展示）。
    fn name(&self) -> &str;

    /// 系统提示词。无提示词的纯工具型 agent 返回 `None`。
    fn system_prompt(&self) -> Option<&str>;

    /// 列出该 Agent 想暴露给 LLM 的工具定义。
    ///
    /// **默认实现**：从 `bundle.tool_registry` 取全部工具（最常用模式）。
    /// **子 trait / 具体实现可覆盖**：做白名单、过滤、按状态动态调整等。
    fn tool_definitions(&self, bundle: &RuntimeBundle) -> Vec<ToolDef> {
        bundle.tool_registry.definitions()
    }
}