Struct AgentDefinition 

pub struct AgentDefinition {
    pub name: AgentName,
    pub role: AgentRole,
    pub description: String,
    pub system_prompt: Vec<String>,
    pub model: Option<AgentModelRef>,
    pub tool_filter: ToolFilter,
    pub tool_choice: Option<ToolChoice>,
    pub generation: Option<GenerationOptions>,
    pub max_steps: Option<u32>,
    pub sub_agents: Vec<AgentName>,
    pub output_schema: Option<Value>,
    pub provider_options: Option<Value>,
}

Agent 定义 — 描述 Agent 的完整静态配置。

这是纯数据结构，不包含运行时行为。katu-agent 中的 AgentRunner 根据此定义来驱动实际的 LLM 循环。

Builder 模式

必填字段通过 AgentDefinition::new() 提供，可选字段通过 with_* 链式设置。

Examples

use katu_core::{AgentDefinition, AgentName, AgentRole, AgentModelRef, ToolFilter};

// 主编码 Agent
let build = AgentDefinition::new("build", AgentRole::Primary)
    .with_description("Default coding agent")
    .with_system_prompt("You are a coding assistant.")
    .with_max_steps(50);

// 只读搜索 subagent
let explore = AgentDefinition::new("explore", AgentRole::SubAgent)
    .with_description("Fast read-only search agent")
    .with_system_prompt("You are a file search specialist.")
    .with_model(AgentModelRef::by_alias("fast"))
    .with_tool_filter(ToolFilter::allow_list(["read_file", "grep", "glob"]))
    .with_max_steps(10);

// 内部 title 生成
let title = AgentDefinition::new("title", AgentRole::Internal)
    .with_description("Generates conversation titles")
    .with_system_prompt("Generate a short title for this conversation.")
    .with_model(AgentModelRef::by_alias("cheap"))
    .with_tool_filter(ToolFilter::None)
    .with_max_steps(1);

Fields

name: AgentName

唯一标识名（snake_case）。

role: AgentRole

Agent 角色。

description: String

人类可读描述。

两个用途：

1. 主 Agent 选择 subagent 时，LLM 据此判断何时调用
2. 配置文件中的说明文本

system_prompt: Vec<String>

System prompt 片段（按顺序拼接）。

使用 Vec 支持组合式 prompt 构建（基础指令 + 项目规则 + 工具说明）。 运行时拼接为单个 system prompt 字符串发送给 LLM。

model: Option<AgentModelRef>

模型引用 — None 表示继承调用者的模型配置。

tool_filter: ToolFilter

工具过滤规则。

tool_choice: Option<ToolChoice>

默认工具选择策略。

None 表示使用 ToolChoice::Auto（模型自行决定）。 常用于 Internal Agent 强制 ToolChoice::None 以禁用工具。

generation: Option<GenerationOptions>

Agent 级生成参数覆盖。

AgentRunner 构建 LlmRequest 时合并优先级： Request > Agent > Model > Provider 默认。

max_steps: Option<u32>

最大循环步数（一次 LLM 调用 → tool_call → result 为一步）。

None 表示由 AgentRunner 全局配置决定。 防止无限循环的安全措施。

sub_agents: Vec<AgentName>

可调度的子 Agent 名称列表。

运行时由 AgentRegistry 解析为具体的 AgentDefinition。 空列表表示不可调度子 Agent。

output_schema: Option<Value>

结构化输出 JSON Schema。

用于 SubAgent 返回结构化数据时约束 LLM 输出格式。 None 表示自由文本输出。

provider_options: Option<Value>

Provider 特有选项透传。

由 Provider adapter 直接消费，katu 框架层不解析。 例如：OpenAI 的 service_tier、Anthropic 的 metadata 等。

Implementations

impl AgentDefinition

pub fn new(name: impl Into<String>, role: AgentRole) -> Self

创建 Agent 定义 — 只需必填的 name 和 role。

pub fn with_description(self, description: impl Into<String>) -> Self

设置描述。

pub fn with_system_prompt(self, prompt: impl Into<String>) -> Self

设置 system prompt（单段，替换已有内容）。

pub fn append_system_prompt(self, prompt: impl Into<String>) -> Self

追加 system prompt 片段。

pub fn with_system_prompts(self, prompts: Vec<String>) -> Self

批量设置 system prompt 片段。

pub fn with_model(self, model: AgentModelRef) -> Self

设置模型引用。

pub fn with_tool_filter(self, filter: ToolFilter) -> Self

设置工具过滤规则。

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

设置默认工具选择策略。

pub fn with_generation(self, generation: GenerationOptions) -> Self

设置生成参数覆盖。

pub fn with_max_steps(self, steps: u32) -> Self

设置最大循环步数。

pub fn with_sub_agents(self, agents: Vec<AgentName>) -> Self

设置可调度的子 Agent 列表。

pub fn add_sub_agent(self, agent: impl Into<String>) -> Self

添加一个子 Agent。

pub fn with_output_schema(self, schema: Value) -> Self

设置结构化输出 schema。

pub fn with_provider_options(self, options: Value) -> Self

设置 provider 透传选项。

pub fn joined_system_prompt(&self) -> String

获取拼接后的完整 system prompt。

多段之间以双换行连接。

Trait Implementations

impl Clone for AgentDefinition

fn clone(&self) -> AgentDefinition

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentDefinition

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentDefinition

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentDefinition

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.