Struct AgentCtx 

pub struct AgentCtx {
    pub base: BaseCtx,
    pub label: String,
    pub model: Model,
    /* private fields */
}

Context for agent operations, providing access to models, tools, and other agents.

Fields

base: BaseCtx

Base context providing fundamental operations.

label: String

Label of the agent.

model: Model

Default AI model instance for completions.

Implementations

impl AgentCtx

pub fn child( &self, agent_name: &str, agent_label: &str, ) -> Result<Self, BoxError>

Creates a child context for a specific agent.

Arguments

• agent_name - Name of the agent to create context for.

pub fn child_base(&self, tool_name: &str) -> Result<BaseCtx, BoxError>

Creates a child base context for a specific tool.

Arguments

• tool_name - Name of the tool to create context for.

pub fn with_caller(&self, caller: Principal) -> Self

Clones the context with a new caller principal.

pub fn completion_iter( self, req: CompletionRequest, resources: Vec<Resource>, ) -> CompletionRunner

Creates a completion runner for iterative processing of completion requests.

pub fn completion_stream( self, req: CompletionRequest, resources: Vec<Resource>, ) -> CompletionStream

Creates a completion stream for processing of completion requests.

Trait Implementations

impl<T> Agent<AgentCtx> for Extractor<T>

where T: JsonSchema + DeserializeOwned + Serialize + Send + Sync,

fn name(&self) -> String

Returns the unique agent name.

fn description(&self) -> String

Returns a concise description of the agent’s capability.

async fn run( &self, ctx: AgentCtx, prompt: String, _resources: Vec<Resource>, ) -> Result<AgentOutput, BoxError>

Executes the agent with the given context and inputs.

fn definition(&self) -> FunctionDefinition

Returns the function definition used for LLM/tool-call integration.

fn supported_resource_tags(&self) -> Vec<String>

Returns resource tags this agent can consume.

fn select_resources(&self, resources: &mut Vec<Resource>) -> Vec<Resource>

Removes and returns resources matching this agent’s supported tags.

fn init( &self, _ctx: C, ) -> impl Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send

Initializes the agent with the given context.

fn tool_dependencies(&self) -> Vec<String>

Returns tool names required by this agent.

impl Agent<AgentCtx> for EchoEngineInfo

fn name(&self) -> String

Returns the agent’s name identifier

fn description(&self) -> String

Returns a description of the agent’s purpose and capabilities.

async fn run( &self, _ctx: AgentCtx, _prompt: String, _resources: Vec<Resource>, ) -> Result<AgentOutput, BoxError>

Executes the agent with the given context and inputs.

fn definition(&self) -> FunctionDefinition

Returns the function definition used for LLM/tool-call integration.

fn supported_resource_tags(&self) -> Vec<String>

Returns resource tags this agent can consume.

fn select_resources(&self, resources: &mut Vec<Resource>) -> Vec<Resource>

Removes and returns resources matching this agent’s supported tags.

fn init( &self, _ctx: C, ) -> impl Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send

Initializes the agent with the given context.

fn tool_dependencies(&self) -> Vec<String>

Returns tool names required by this agent.

impl Agent<AgentCtx> for RemoteAgent

fn name(&self) -> String

Returns the unique agent name.

fn description(&self) -> String

Returns a concise description of the agent’s capability.

fn definition(&self) -> FunctionDefinition

Returns the function definition used for LLM/tool-call integration.

fn supported_resource_tags(&self) -> Vec<String>

Returns resource tags this agent can consume.

async fn run( &self, ctx: AgentCtx, prompt: String, resources: Vec<Resource>, ) -> Result<AgentOutput, BoxError>

Executes the agent with the given context and inputs.

fn select_resources(&self, resources: &mut Vec<Resource>) -> Vec<Resource>

Removes and returns resources matching this agent’s supported tags.

fn init( &self, _ctx: C, ) -> impl Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send

Initializes the agent with the given context.

fn tool_dependencies(&self) -> Vec<String>

Returns tool names required by this agent.

impl Agent<AgentCtx> for SubAgent

fn name(&self) -> String

Returns the unique agent name.

fn description(&self) -> String

Returns a concise description of the agent’s capability.

fn definition(&self) -> FunctionDefinition

Returns the function definition used for LLM/tool-call integration.

fn tool_dependencies(&self) -> Vec<String>

Returns tool names required by this agent.

fn supported_resource_tags(&self) -> Vec<String>

Returns resource tags this agent can consume.

async fn run( &self, ctx: AgentCtx, prompt: String, resources: Vec<Resource>, ) -> Result<AgentOutput, BoxError>

Executes the agent with the given context and inputs.

fn select_resources(&self, resources: &mut Vec<Resource>) -> Vec<Resource>

Removes and returns resources matching this agent’s supported tags.

fn init( &self, _ctx: C, ) -> impl Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send

Initializes the agent with the given context.

impl Agent<AgentCtx> for SubAgentManager

fn name(&self) -> String

Returns the unique agent name.

fn description(&self) -> String

Returns a concise description of the agent’s capability.

fn definition(&self) -> FunctionDefinition

Returns the function definition used for LLM/tool-call integration.

fn supported_resource_tags(&self) -> Vec<String>

Returns resource tags this agent can consume.

async fn init(&self, ctx: AgentCtx) -> Result<(), BoxError>

Initializes the agent with the given context.

async fn run( &self, ctx: AgentCtx, prompt: String, resources: Vec<Resource>, ) -> Result<AgentOutput, BoxError>

Executes the agent with the given context and inputs.

fn select_resources(&self, resources: &mut Vec<Resource>) -> Vec<Resource>

Removes and returns resources matching this agent’s supported tags.

fn tool_dependencies(&self) -> Vec<String>

Returns tool names required by this agent.

impl Agent<AgentCtx> for ToolsSearch

fn name(&self) -> String

Returns the unique agent name.

fn description(&self) -> String

Returns a concise description of the agent’s capability.

fn definition(&self) -> FunctionDefinition

Returns the function definition used for LLM/tool-call integration.

async fn run( &self, ctx: AgentCtx, prompt: String, _resources: Vec<Resource>, ) -> Result<AgentOutput, BoxError>

Executes the agent with the given context and inputs.

fn supported_resource_tags(&self) -> Vec<String>

Returns resource tags this agent can consume.

fn select_resources(&self, resources: &mut Vec<Resource>) -> Vec<Resource>

Removes and returns resources matching this agent’s supported tags.

fn init( &self, _ctx: C, ) -> impl Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send

Initializes the agent with the given context.

fn tool_dependencies(&self) -> Vec<String>

Returns tool names required by this agent.

impl Agent<AgentCtx> for ToolsSelect

fn name(&self) -> String

Returns the unique agent name.

fn description(&self) -> String

Returns a concise description of the agent’s capability.

fn definition(&self) -> FunctionDefinition

Returns the function definition used for LLM/tool-call integration.

async fn run( &self, ctx: AgentCtx, prompt: String, _resources: Vec<Resource>, ) -> Result<AgentOutput, BoxError>

Executes the agent with the given context and inputs.

fn supported_resource_tags(&self) -> Vec<String>

Returns resource tags this agent can consume.

fn select_resources(&self, resources: &mut Vec<Resource>) -> Vec<Resource>

Removes and returns resources matching this agent’s supported tags.

fn init( &self, _ctx: C, ) -> impl Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send

Initializes the agent with the given context.

fn tool_dependencies(&self) -> Vec<String>

Returns tool names required by this agent.

impl AgentContext for AgentCtx

fn tool_definitions(&self, names: Option<&[String]>) -> Vec<FunctionDefinition>

Retrieves definitions for available tools.

Arguments

• names - Optional filter for specific tool names.

Returns

Vector of function definitions for the requested tools.

async fn remote_tool_definitions( &self, endpoint: Option<&str>, names: Option<&[String]>, ) -> Result<Vec<FunctionDefinition>, BoxError>

Retrieves definitions for available tools in the remote engines.

Arguments

• endpoint - Optional filter for specific remote engine endpoint;
• names - Optional filter for specific tool names.

Returns

Vector of function definitions for the requested tools.

async fn select_tool_resources( &self, prefixed_name: &str, resources: &mut Vec<Resource>, ) -> Vec<Resource>

Extracts resources from the provided list based on the tool’s supported tags.

fn agent_definitions(&self, names: Option<&[String]>) -> Vec<FunctionDefinition>

Retrieves definitions for available agents.

Arguments

• names - Optional filter for specific agent names;

Returns

Vector of function definitions for the requested agents.

async fn remote_agent_definitions( &self, endpoint: Option<&str>, names: Option<&[String]>, ) -> Result<Vec<FunctionDefinition>, BoxError>

Retrieves definitions for available agents in the remote engines.

Arguments

• endpoint - Optional filter for specific remote engine endpoint;
• names - Optional filter for specific agent names.

Returns

Vector of function definitions for the requested agents.

async fn select_agent_resources( &self, prefixed_name: &str, resources: &mut Vec<Resource>, ) -> Vec<Resource>

Extracts resources from the provided list based on the agent’s supported tags.

async fn definitions(&self, names: Option<&[String]>) -> Vec<FunctionDefinition>

Retrieves definitions for available tools and agents, including those from remote engines.

async fn tool_call( &self, input: ToolInput<Json>, ) -> Result<(ToolOutput<Json>, Option<Principal>), BoxError>

Executes a tool call with the given arguments

Arguments

• name - Name of the tool to call
• args - Arguments for the tool call as a JSON string

Returns

Tuple containing the result string and a boolean indicating if further processing is needed

fn agent_run( self, input: AgentInput, ) -> impl Future<Output = Result<(AgentOutput, Option<Principal>), BoxError>> + Send

Runs a local agent.

Arguments

• args - Tool input arguments, AgentInput.

Returns

AgentOutput containing the result of the agent execution.

async fn remote_agent_run( &self, endpoint: &str, args: AgentInput, ) -> Result<AgentOutput, BoxError>

Runs a remote agent via HTTP RPC.

Arguments

• endpoint - Remote endpoint URL;
• args - Tool input arguments, AgentInput. The meta field will be set to the current agent’s metadata.

Returns

AgentOutput containing the result of the agent execution.

impl BaseContext for AgentCtx

async fn remote_tool_call( &self, endpoint: &str, args: ToolInput<Json>, ) -> Result<ToolOutput<Json>, BoxError>

Executes a remote tool call via HTTP RPC.

Arguments

• endpoint - Remote endpoint URL;
• args - Tool input arguments, ToolInput.

Returns

ToolOutput containing the final result.

impl CacheFeatures for AgentCtx

fn cache_contains(&self, key: &str) -> bool

Checks if a key exists in the cache.

async fn cache_get<T>(&self, key: &str) -> Result<T, BoxError>

where T: DeserializeOwned,

Gets a cached value by key, returns error if not found or deserialization fails.

async fn cache_get_with<T, F>(&self, key: &str, init: F) -> Result<T, BoxError>

where T: Sized + DeserializeOwned + Serialize + Send, F: Future<Output = Result<(T, Option<CacheExpiry>), BoxError>> + Send + 'static,

Gets a cached value or initializes it if missing.

If key doesn’t exist, calls init function to create value and cache it.

async fn cache_set<T>(&self, key: &str, val: (T, Option<CacheExpiry>))

where T: Sized + Serialize + Send,

Sets a value in cache with optional expiration policy.

async fn cache_set_if_not_exists<T>( &self, key: &str, val: (T, Option<CacheExpiry>), ) -> bool

where T: Sized + Serialize + Send,

Sets a value in cache if key doesn’t exist, returns true if set.

async fn cache_delete(&self, key: &str) -> bool

Deletes a cached value by key, returns true if key existed.

fn cache_raw_iter( &self, ) -> impl Iterator<Item = (Arc<String>, Arc<(Bytes, Option<CacheExpiry>)>)>

Returns an iterator over all cached items with raw value.

impl CacheStoreFeatures for AgentCtx

fn cache_store_init<'life0, 'life1, 'async_trait, T, F>( &'life0 self, key: &'life1 str, init: F, ) -> Pin<Box<dyn Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: DeserializeOwned + Serialize + Send + 'async_trait, F: Future<Output = Result<T, Box<dyn Error + Sync + Send>>> + Send + 'static + 'async_trait, Self: 'async_trait,

Initializes a cached value from storage, or creates it with init if missing.

fn cache_store_get<'life0, 'life1, 'async_trait, T>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(T, UpdateVersion), Box<dyn Error + Sync + Send>>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: DeserializeOwned + Serialize + Send + 'async_trait, Self: 'async_trait,

Returns a value and its storage version, loading it into cache if needed.

fn cache_store_set<'life0, 'life1, 'async_trait, T>( &'life0 self, key: &'life1 str, val: T, version: Option<UpdateVersion>, ) -> Pin<Box<dyn Future<Output = Result<UpdateVersion, Box<dyn Error + Sync + Send>>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, T: DeserializeOwned + Serialize + Send + 'async_trait, Self: 'async_trait,

Persists a value to storage and updates the cache on success.

fn cache_store_delete<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), Box<dyn Error + Sync + Send>>> + Send + 'async_trait>>

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

Deletes a value from both cache and storage.

impl CanisterCaller for AgentCtx

async fn canister_query<In: ArgumentEncoder + Send, Out: CandidType + for<'a> Deserialize<'a>>( &self, canister: &Principal, method: &str, args: In, ) -> Result<Out, BoxError>

Performs a query call to a canister (read-only, no state changes).

Arguments

• canister - Target canister principal;
• method - Method name to call;
• args - Input arguments encoded in Candid format.

async fn canister_update<In: ArgumentEncoder + Send, Out: CandidType + for<'a> Deserialize<'a>>( &self, canister: &Principal, method: &str, args: In, ) -> Result<Out, BoxError>

Performs an update call to a canister (may modify state).

Arguments

• canister - Target canister principal;
• method - Method name to call;
• args - Input arguments encoded in Candid format.

impl Clone for AgentCtx

fn clone(&self) -> AgentCtx

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl CompletionFeatures for AgentCtx

fn completion( &self, req: CompletionRequest, resources: Vec<Resource>, ) -> impl Future<Output = Result<AgentOutput, BoxError>> + Send

Executes a completion request with automatic tool call handling.

This method handles the completion request in a loop, automatically executing any tool calls that are returned by the model and feeding their results back into the model until no more tool calls need to be processed.

Arguments

• req - CompletionRequest containing the input parameters;
• resources - Optional list of resources to use for tool calls.

Returns

AgentOutput containing the final completion result.

Process Flow

1. Makes initial completion request to the model;
2. If tool calls are returned:
   • Executes each tool call;
   • Adds tool results to the chat history;
   • Repeats the completion with updated history;
3. Returns final result when no more tool calls need processing.

fn model_name(&self) -> String

Returns the name of the model.

impl HttpFeatures for AgentCtx

async fn https_call( &self, url: &str, method: Method, headers: Option<HeaderMap>, body: Option<Vec<u8>>, ) -> Result<Response, BoxError>

Makes an HTTPs request.

Arguments

• url - Target URL, should start with https://;
• method - HTTP method (GET, POST, etc.);
• headers - Optional HTTP headers;
• body - Optional request body (default empty).

async fn https_signed_call( &self, url: &str, method: Method, message_digest: [u8; 32], headers: Option<HeaderMap>, body: Option<Vec<u8>>, ) -> Result<Response, BoxError>

Makes a signed HTTPs request with message authentication.

Arguments

• url - Target URL;
• method - HTTP method (GET, POST, etc.);
• message_digest - 32-byte message digest for signing;
• headers - Optional HTTP headers;
• body - Optional request body (default empty).

async fn https_signed_rpc<T>( &self, endpoint: &str, method: &str, args: impl Serialize + Send, ) -> Result<T, BoxError>

where T: DeserializeOwned,

Makes a signed CBOR-encoded RPC call.

Arguments

• endpoint - URL endpoint to send the request to;
• method - RPC method name to call;
• args - Arguments to serialize as CBOR and send with the request.

impl KeysFeatures for AgentCtx

async fn a256gcm_key( &self, derivation_path: Vec<Vec<u8>>, ) -> Result<[u8; 32], BoxError>

Derives a 256-bit AES-GCM key from the given derivation path.

async fn ed25519_sign_message( &self, derivation_path: Vec<Vec<u8>>, message: &[u8], ) -> Result<[u8; 64], BoxError>

Signs a message using Ed25519 signature scheme from the given derivation path.

async fn ed25519_verify( &self, derivation_path: Vec<Vec<u8>>, message: &[u8], signature: &[u8], ) -> Result<(), BoxError>

Verifies an Ed25519 signature from the given derivation path.

async fn ed25519_public_key( &self, derivation_path: Vec<Vec<u8>>, ) -> Result<[u8; 32], BoxError>

Gets the public key for Ed25519 from the given derivation path.

async fn secp256k1_sign_message_bip340( &self, derivation_path: Vec<Vec<u8>>, message: &[u8], ) -> Result<[u8; 64], BoxError>

Signs a message using Secp256k1 BIP340 Schnorr signature from the given derivation path.

async fn secp256k1_verify_bip340( &self, derivation_path: Vec<Vec<u8>>, message: &[u8], signature: &[u8], ) -> Result<(), BoxError>

Verifies a Secp256k1 BIP340 Schnorr signature from the given derivation path.

async fn secp256k1_sign_message_ecdsa( &self, derivation_path: Vec<Vec<u8>>, message: &[u8], ) -> Result<[u8; 64], BoxError>

Signs a message using Secp256k1 ECDSA signature from the given derivation path. The message will be hashed with SHA-256 before signing.

async fn secp256k1_sign_digest_ecdsa( &self, derivation_path: Vec<Vec<u8>>, message_hash: &[u8], ) -> Result<[u8; 64], BoxError>

Signs a message hash using Secp256k1 ECDSA signature from the given derivation path.

async fn secp256k1_verify_ecdsa( &self, derivation_path: Vec<Vec<u8>>, message_hash: &[u8], signature: &[u8], ) -> Result<(), BoxError>

Verifies a Secp256k1 ECDSA signature from the given derivation path.

async fn secp256k1_public_key( &self, derivation_path: Vec<Vec<u8>>, ) -> Result<[u8; 33], BoxError>

Gets the compressed SEC1-encoded public key for Secp256k1 from the given derivation path.

impl StateFeatures for AgentCtx

fn engine_id(&self) -> &Principal

Returns the engine principal.

fn engine_name(&self) -> &str

Returns the engine name.

fn caller(&self) -> &Principal

Returns the verified caller principal if available. A non-anonymous principal indicates that the request was verified using ICP blockchain’s signature verification algorithm. Details: https://github.com/ldclabs/ic-auth

fn meta(&self) -> &RequestMeta

Returns metadata attached to the current request.

fn cancellation_token(&self) -> CancellationToken

Returns the cancellation token for the current execution context. Each call level has its own token scope. For example, when an agent calls a tool, the tool receives a child token of the agent’s token. Cancelling the agent token cancels all child calls, while cancelling a child token does not affect the parent context.

fn time_elapsed(&self) -> Duration

Returns the time elapsed since the context was created.

impl StoreFeatures for AgentCtx

async fn store_get(&self, path: &Path) -> Result<(Bytes, ObjectMeta), BoxError>

Retrieves data from storage at the specified path.

async fn store_list( &self, prefix: Option<&Path>, offset: &Path, ) -> Result<Vec<ObjectMeta>, BoxError>

Lists objects in storage with optional prefix and offset filters.

Arguments

• prefix - Optional path prefix to filter results;
• offset - Optional path to start listing from (exclude).

async fn store_put( &self, path: &Path, mode: PutMode, value: Bytes, ) -> Result<PutResult, BoxError>

Stores data at the specified path with a given write mode.

Arguments

• path - Target storage path;
• mode - Write mode (Create, Overwrite, etc.);
• value - Data to store as bytes.

async fn store_rename_if_not_exists( &self, from: &Path, to: &Path, ) -> Result<(), BoxError>

Renames a storage object if the target path doesn’t exist.

Arguments

• from - Source path;
• to - Destination path.

async fn store_delete(&self, path: &Path) -> Result<(), BoxError>

Deletes data at the specified path.

Arguments

• path - Path of the object to delete.