Struct Agent 

pub struct Agent {
    pub extension_manager: Arc<ExtensionManager>,
    /* private fields */
}

The main aster Agent

Fields

extension_manager: Arc<ExtensionManager>

Implementations

impl Agent

pub fn new() -> Self

pub fn with_session_store(self, store: Arc<dyn SessionStore>) -> Self

设置自定义 session 存储

允许应用层注入自己的存储实现，而不是使用默认的 SQLite 存储。 如果设置为 None，会回退到全局 SessionManager。

Example

let store = Arc::new(MyCustomStore::new());
let agent = Agent::new().with_session_store(store);

pub fn session_store(&self) -> Option<&Arc<dyn SessionStore>>

获取当前的 session 存储引用

pub fn with_identity(self, identity: AgentIdentity) -> Self

设置 Agent 身份配置（Builder 模式）

允许应用层完全控制 Agent 的身份，包括名称、语言、描述等。 这会替换默认的 “aster by Block” 身份。

注意：此方法使用 try_lock，如果锁被占用会静默失败。 建议在 Agent 创建后立即调用，或使用异步版本 set_identity()。

Example

use aster::agents::{Agent, AgentIdentity};

let identity = AgentIdentity::new("ProxyCast 助手")
    .with_language("Chinese")
    .with_description("一个专业的 AI 代理服务助手");

let agent = Agent::new().with_identity(identity);

pub async fn set_identity(&self, identity: AgentIdentity)

设置 Agent 身份（异步方法）

用于在 Agent 创建后动态修改身份配置。 这是在异步上下文中设置身份的推荐方式。

pub fn with_tool_config(config: ToolRegistrationConfig) -> Self

Create a new Agent with custom tool registration configuration

This allows customizing which tools are registered and their configuration.

Arguments

• config - Configuration for tool registration

Requirements: 11.3, 11.4

pub fn tool_registry(&self) -> &Arc<RwLock<ToolRegistry>>

Get a reference to the tool registry

Requirements: 11.3

pub fn file_read_history(&self) -> &SharedFileReadHistory

Get a reference to the shared file read history

This is useful for tools that need to track file reads.

pub async fn register_mcp_tool( &self, name: String, description: String, input_schema: Value, server_name: String, )

Register an MCP tool with the registry

This method allows registering MCP tools from extensions into the native tool registry. Native tools have priority over MCP tools with the same name.

Arguments

• name - The tool name
• description - Tool description
• input_schema - JSON schema for tool input
• server_name - Name of the MCP server providing this tool

Requirements: 11.4, 11.5

pub async fn reset_retry_attempts(&self)

Reset the retry attempts counter to 0

pub async fn increment_retry_attempts(&self) -> u32

Increment the retry attempts counter and return the new value

pub async fn get_retry_attempts(&self) -> u32

Get the current retry attempts count

pub async fn set_scheduler(&self, scheduler: Arc<dyn SchedulerTrait>)

pub async fn provider(&self) -> Result<Arc<dyn Provider>, Error>

Get a reference count clone to the provider

pub async fn is_frontend_tool(&self, name: &str) -> bool

Check if a tool is a frontend tool

pub async fn get_frontend_tool(&self, name: &str) -> Option<FrontendTool>

Get a reference to a frontend tool

pub async fn add_final_output_tool(&self, response: Response)

pub async fn add_sub_recipes(&self, sub_recipes_to_add: Vec<SubRecipe>)

pub async fn apply_recipe_components( &self, sub_recipes: Option<Vec<SubRecipe>>, response: Option<Response>, include_final_output: bool, )

pub async fn dispatch_tool_call( &self, tool_call: CallToolRequestParam, request_id: String, cancellation_token: Option<CancellationToken>, session: &Session, ) -> (String, Result<ToolCallResult, ErrorData>)

Dispatch a single tool call to the appropriate client

pub async fn save_extension_state(&self, session: &SessionConfig) -> Result<()>

Save current extension state to session metadata Should be called after any extension add/remove operation

pub async fn add_extension( &self, extension: ExtensionConfig, ) -> ExtensionResult<()>

pub async fn subagents_enabled(&self) -> bool

pub async fn list_tools(&self, extension_name: Option<String>) -> Vec<Tool>

pub async fn remove_extension(&self, name: &str) -> Result<()>

pub async fn list_extensions(&self) -> Vec<String>

pub async fn get_extension_configs(&self) -> Vec<ExtensionConfig>

pub async fn handle_confirmation( &self, request_id: String, confirmation: PermissionConfirmation, )

Handle a confirmation response for a tool request

pub async fn reply( &self, user_message: Message, session_config: SessionConfig, cancel_token: Option<CancellationToken>, ) -> Result<BoxStream<'_, Result<AgentEvent>>>

pub async fn extend_system_prompt(&self, instruction: String)

pub async fn update_provider( &self, provider: Arc<dyn Provider>, session_id: &str, ) -> Result<()>

pub async fn override_system_prompt(&self, template: String)

Override the system prompt with a custom template

pub async fn list_extension_prompts(&self) -> HashMap<String, Vec<Prompt>>

pub async fn get_prompt( &self, name: &str, arguments: Value, ) -> Result<GetPromptResult>

pub async fn get_plan_prompt(&self) -> Result<String>

pub async fn handle_tool_result( &self, id: String, result: ToolResult<CallToolResult>, )

pub async fn create_recipe(&self, messages: Conversation) -> Result<Recipe>

impl Agent

pub async fn execute_command( &self, message_text: &str, session_id: &str, ) -> Result<Option<Message>>

impl Agent

pub async fn prepare_tools_and_prompt( &self, working_dir: &Path, session_prompt: Option<&str>, ) -> Result<(Vec<Tool>, Vec<Tool>, String)>

impl Agent

pub async fn handle_schedule_management( &self, arguments: Value, _request_id: String, ) -> ToolResult<Vec<Content>>

Handle schedule management tool calls

impl Agent

pub fn create_tool_context( session: &Session, cancellation_token: Option<CancellationToken>, ) -> ToolContext

Create a ToolContext from a Session

This helper function creates a ToolContext suitable for use with the ToolRegistry from the current session information.

Requirements: 8.4

pub fn create_permission_context(session: &Session) -> PermissionContext

Create a PermissionContext from a Session

This helper function creates a PermissionContext suitable for use with the ToolPermissionManager from the current session information.

Requirements: 8.1, 8.2

pub async fn execute_tool_with_registry( registry: &ToolRegistry, tool_name: &str, params: Value, session: &Session, cancellation_token: Option<CancellationToken>, on_permission_request: Option<PermissionRequestCallback>, ) -> Result<ToolResult, ToolError>

Execute a tool through the ToolRegistry with permission checking and audit logging

This method provides a unified interface for executing tools through the ToolRegistry, integrating:

• Permission checking via ToolPermissionManager
• Audit logging via AuditLogger
• User confirmation handling for ‘ask’ permission behavior

Arguments

• registry - The ToolRegistry containing registered tools
• tool_name - Name of the tool to execute
• params - Tool parameters as JSON
• session - Current session
• cancellation_token - Optional cancellation token
• on_permission_request - Optional callback for permission requests

Returns

• Ok(ToolResult) - The tool execution result
• Err(ToolError) - If permission denied or execution fails

Requirements: 8.1, 8.2, 8.3, 8.4, 8.5

pub fn log_tool_execution( audit_logger: &AuditLogger, tool_name: &str, params: &Value, session: &Session, success: bool, duration: Duration, error_message: Option<&str>, )

Log a tool execution to the audit logger

This helper function logs tool execution events to the audit logger, including success/failure status, duration, and relevant metadata.

Requirements: 8.5

pub fn log_permission_denied( audit_logger: &AuditLogger, tool_name: &str, params: &Value, session: &Session, reason: &str, )

Log a permission denial to the audit logger

This helper function logs permission denial events to the audit logger.

Requirements: 8.5

pub fn check_tool_permission( permission_manager: &ToolPermissionManager, tool_name: &str, params: &Value, session: &Session, ) -> Result<(), String>

Check tool permissions using ToolPermissionManager

This method checks if a tool execution is allowed based on the configured permission rules.

Arguments

• permission_manager - The ToolPermissionManager to use
• tool_name - Name of the tool to check
• params - Tool parameters as JSON
• session - Current session

Returns

• Ok(()) - If permission is granted
• Err(reason) - If permission is denied, with the denial reason

Requirements: 8.1, 8.2, 8.3

pub async fn execute_tool_with_checks( registry: &ToolRegistry, permission_manager: Option<&ToolPermissionManager>, audit_logger: Option<&AuditLogger>, tool_name: &str, params: Value, session: &Session, cancellation_token: Option<CancellationToken>, ) -> Result<ToolResult, String>

Execute a tool call with integrated permission checking and audit logging

This is a higher-level wrapper that combines permission checking, tool execution, and audit logging into a single operation.

Arguments

• registry - The ToolRegistry containing registered tools
• permission_manager - Optional ToolPermissionManager for permission checks
• audit_logger - Optional AuditLogger for logging
• tool_name - Name of the tool to execute
• params - Tool parameters as JSON
• session - Current session
• cancellation_token - Optional cancellation token

Returns

• Ok(ToolResult) - The tool execution result
• Err(String) - Error message if permission denied or execution fails

Requirements: 8.1, 8.2, 8.3, 8.4, 8.5

pub async fn execute_tool_with_user_confirmation( registry: &ToolRegistry, permission_manager: Option<&ToolPermissionManager>, audit_logger: Option<&AuditLogger>, tool_name: &str, params: Value, session: &Session, cancellation_token: Option<CancellationToken>, on_permission_request: Option<PermissionRequestCallback>, ) -> Result<ToolResult, String>

Execute a tool call with user confirmation support for ‘ask’ permission behavior

This method extends execute_tool_with_checks to support the ‘ask’ permission behavior, where the user is prompted to confirm tool execution.

Arguments

• registry - The ToolRegistry containing registered tools
• permission_manager - Optional ToolPermissionManager for permission checks
• audit_logger - Optional AuditLogger for logging
• tool_name - Name of the tool to execute
• params - Tool parameters as JSON
• session - Current session
• cancellation_token - Optional cancellation token
• on_permission_request - Callback for handling ‘ask’ permission behavior

Returns

• Ok(ToolResult) - The tool execution result
• Err(String) - Error message if permission denied or execution fails

Requirements: 8.1, 8.2, 8.3, 8.4

pub fn create_permission_callback( request_id: String, _confirmation_tx: Sender<(String, PermissionConfirmation)>, ) -> PermissionRequestCallback

Create a permission request callback that uses the Agent’s confirmation channel

This method creates a callback that can be used with execute_tool_with_user_confirmation to handle ‘ask’ permission behavior by sending confirmation requests through the Agent’s existing confirmation channel.

Arguments

• request_id - The tool request ID for tracking
• confirmation_tx - The confirmation sender channel

Returns

A callback that sends permission requests and waits for user confirmation

Requirements: 8.2, 8.3

pub fn log_permission_check( audit_logger: &AuditLogger, tool_name: &str, params: &Value, session: &Session, allowed: bool, reason: Option<&str>, )

Log a permission check result to the audit logger

This helper function logs permission check events to the audit logger, including the result and any relevant metadata.

Requirements: 8.5

Trait Implementations

impl Default for Agent

fn default() -> Self

Returns the “default value” for a type.