Trait Agent 

pub trait Agent: Send + Sync {
    // Required methods
    fn think<'life0, 'life1, 'async_trait>(
        &'life0 self,
        context: &'life1 AgentContext,
    ) -> Pin<Box<dyn Future<Output = AgentDecision> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn name(&self) -> &str;

    // Provided methods
    fn description(&self) -> Option<&str> { ... }
    fn run<'life0, 'async_trait>(
        &'life0 self,
        input: AgentInput,
    ) -> Pin<Box<dyn Future<Output = Result<AgentOutput, AgentError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn run_stream(
        &self,
        _input: AgentInput,
    ) -> BoxStream<'static, Result<ChannelEvent, AgentError>> { ... }
    fn run_with<'life0, 'life1, 'async_trait>(
        &'life0 self,
        executor: &'life1 dyn AgentExecutor,
        input: AgentInput,
    ) -> Pin<Box<dyn Future<Output = Result<AgentOutput, AgentError>> + Send + 'async_trait>>
       where Self: Sized + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
}

Agent trait - 智能体的抽象接口。

Agent 负责思考、决策和规划。它可以：

• 独立运行（处理简单任务）
• 使用内置执行能力（处理复杂任务）
• 调用 Tool/MCP/Skill/A2A 等外部能力

设计原则

Agent trait 只定义决策接口（think），执行能力（run/run_stream）由具体实现提供。

决策与执行分离

• 决策层 (think): 每个 Agent 类型有不同的思考策略
• 执行层 (run/run_stream): 所有 Agent 共享相同的执行能力

使用方式

use rucora_core::agent::{Agent, AgentContext, AgentDecision, AgentInput, AgentOutput};
use async_trait::async_trait;

struct MyAgent;

#[async_trait]
impl Agent for MyAgent {
    async fn think(&self, context: &AgentContext) -> AgentDecision {
        // 自定义决策逻辑
        AgentDecision::Return(serde_json::json!({"content": "Hello"}))
    }

    fn name(&self) -> &str { "my_agent" }
}

内置执行能力

如果 Agent 需要工具调用、流式输出等能力，可以组合 DefaultExecution：

use rucora::agent::execution::DefaultExecution;
use rucora_core::agent::Agent;

struct MyAgent {
    execution: DefaultExecution,
    // ... 其他字段
}

impl Agent for MyAgent {
    // ... 实现 think 方法
     
    // DefaultExecution 提供默认的 run/run_stream 实现
}

Required Methods

fn think<'life0, 'life1, 'async_trait>( &'life0 self, context: &'life1 AgentContext, ) -> Pin<Box<dyn Future<Output = AgentDecision> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

思考：分析当前情况，决定下一步行动。

这是 Agent 的核心方法，返回决策结果。

fn name(&self) -> &str

获取 Agent 名称。

Provided Methods

fn description(&self) -> Option<&str>

获取 Agent 描述（可选）。

返回 Agent 的简短描述，用于调试和日志。

fn run<'life0, 'async_trait>( &'life0 self, input: AgentInput, ) -> Pin<Box<dyn Future<Output = Result<AgentOutput, AgentError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

运行 Agent（非流式）。

默认实现适用于简单场景（直接返回结果）。 需要工具调用等复杂能力的 Agent 应该使用 run_with() 方法配合 AgentExecutor。

默认行为

默认实现会循环调用 think() 直到返回 Return 或 Stop。 如果返回 Chat 或 ToolCall，会返回错误（需要 Runtime 支持）。

配置

默认最大步骤数为 20。如果需要自定义，请使用 run_with() 方法。

示例

use rucora_core::agent::{Agent, AgentInput};

let output = agent.run(AgentInput::new("你好")).await?;

fn run_stream( &self, _input: AgentInput, ) -> BoxStream<'static, Result<ChannelEvent, AgentError>>

运行 Agent（流式）。

默认实现返回错误（需要具体实现提供流式能力）。

示例

use rucora_core::agent::{Agent, AgentInput};
use futures_util::StreamExt;

let mut stream = agent.run_stream(AgentInput::new("你好"));
while let Some(event) = stream.next().await {
    match event? {
        rucora_core::channel::types::ChannelEvent::TokenDelta(delta) => {
            print!("{}", delta.delta);
        }
        _ => {}
    }
}

fn run_with<'life0, 'life1, 'async_trait>( &'life0 self, executor: &'life1 dyn AgentExecutor, input: AgentInput, ) -> Pin<Box<dyn Future<Output = Result<AgentOutput, AgentError>> + Send + 'async_trait>>

where Self: Sized + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

运行 Agent（使用执行器）。

此方法允许使用外部执行器来运行 Agent。 这是实现 dyn 兼容的关键方法。

参数

• executor: 执行器，负责实际的运行逻辑
• input: 用户输入

示例

use rucora_core::agent::{Agent, AgentInput, AgentExecutor};

let output = agent.run_with(executor, AgentInput::new("你好")).await?;

Implementors