Struct InvocationContext 

pub struct InvocationContext { /* private fields */ }

Available on crate feature runner only.

Runtime context for a single agent invocation.

Holds the agent, session, identity, and optional services (artifacts, memory, secrets) needed during execution. Created by the Runner for each run() call.

Implementations

impl InvocationContext

pub fn new_typed( invocation_id: String, agent: Arc<dyn Agent>, user_id: UserId, app_name: AppName, session_id: SessionId, user_content: Content, session: Arc<dyn Session>, ) -> Result<InvocationContext, AdkError>

Create a new invocation context from validated typed identifiers.

pub fn new( invocation_id: String, agent: Arc<dyn Agent>, user_id: String, app_name: String, session_id: String, user_content: Content, session: Arc<dyn Session>, ) -> Result<InvocationContext, AdkError>

Create a new invocation context from raw string identifiers.

Validates and converts the string identifiers into typed wrappers. Prefer new_typed when you already have validated types.

pub fn with_mutable_session_typed( invocation_id: String, agent: Arc<dyn Agent>, user_id: UserId, app_name: AppName, session_id: SessionId, user_content: Content, session: Arc<MutableSession>, ) -> Result<InvocationContext, AdkError>

Create an invocation context that reuses an existing mutable session and validated typed identifiers.

pub fn with_mutable_session( invocation_id: String, agent: Arc<dyn Agent>, user_id: String, app_name: String, session_id: String, user_content: Content, session: Arc<MutableSession>, ) -> Result<InvocationContext, AdkError>

Create an InvocationContext with an existing MutableSession. This allows sharing the same mutable session across multiple contexts (e.g., for agent transfers).

pub fn with_branch(self, branch: String) -> InvocationContext

Set the event branch identifier for this context.

pub fn with_artifacts(self, artifacts: Arc<dyn Artifacts>) -> InvocationContext

Attach an artifact storage service to this context.

pub fn with_memory(self, memory: Arc<dyn Memory>) -> InvocationContext

Attach a memory service for RAG/semantic search.

pub fn with_run_config(self, config: RunConfig) -> InvocationContext

Set the run configuration (streaming mode, history limits, etc.).

pub fn with_request_context(self, ctx: RequestContext) -> InvocationContext

Set the request context from the server’s auth middleware bridge.

When set, user_id() returns request_context.user_id (overriding the session-scoped identity), and user_scopes() returns request_context.scopes. This is the explicit authenticated user override — RequestContext remains separate from ExecutionIdentity and AdkIdentity (it does not carry session or invocation IDs).

pub fn with_shared_state(self, shared: Arc<SharedState>) -> InvocationContext

Set the shared state for parallel agent coordination.

pub fn with_secret_service( self, service: Arc<dyn SecretService>, ) -> InvocationContext

Set the secret service for runtime secret retrieval.

When configured, tools can call ctx.get_secret("name") to retrieve secrets from the configured provider (e.g., AWS Secrets Manager, Azure Key Vault, GCP Secret Manager).

pub fn with_cancellation_token( self, token: CancellationToken, ) -> InvocationContext

Attach a cooperative cancellation token.

When set, is_cancelled reflects this token, so agents and tools can detect external cancellation during long-running work.

pub fn mutable_session(&self) -> &Arc<MutableSession>

Get a reference to the mutable session. This allows the Runner to apply state deltas when events are processed.

Trait Implementations

impl CallbackContext for InvocationContext

fn artifacts(&self) -> Option<Arc<dyn Artifacts>>

Returns the artifact store, if one is configured.

fn shared_state(&self) -> Option<Arc<SharedState>>

Returns the shared state for parallel agent coordination. Returns None when not running inside a ParallelAgent with shared state enabled.

fn tool_outcome(&self) -> Option<ToolOutcome>

Returns structured metadata about the most recent tool execution. Available in after-tool callbacks and plugin hooks. Returns None when not in a tool execution context.

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

Returns the name of the tool about to be executed. Available in before-tool and after-tool callback contexts.

fn tool_input(&self) -> Option<&Value>

Returns the input arguments for the tool about to be executed. Available in before-tool and after-tool callback contexts.

impl InvocationContext for InvocationContext

fn agent(&self) -> Arc<dyn Agent>

Returns the agent being executed.

fn memory(&self) -> Option<Arc<dyn Memory>>

Returns the memory service, if one is configured.

fn session(&self) -> &dyn Session

Returns the current session.

fn run_config(&self) -> &RunConfig

Returns the run configuration for this invocation.

fn end_invocation(&self)

Signals that this invocation should end after the current turn.

fn ended(&self) -> bool

Returns whether the invocation has been ended.

fn is_cancelled(&self) -> bool

Returns true if this invocation has been cancelled.

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

Returns the scopes granted to the current user for this invocation.

fn request_metadata(&self) -> HashMap<String, Value>

Returns the request metadata from the auth middleware bridge, if present.

fn get_secret<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<String>, AdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, InvocationContext: 'async_trait,

Retrieve a secret by name from the configured secret provider.

fn get_secret_for<'life0, 'life1, 'async_trait>( &'life0 self, request: &'life1 SecretRequest, ) -> Pin<Box<dyn Future<Output = Result<Option<String>, AdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, InvocationContext: 'async_trait,

Resolves a secret for a described access.

impl ReadonlyContext for InvocationContext

fn invocation_id(&self) -> &str

Returns the current invocation identifier.

fn agent_name(&self) -> &str

Returns the name of the currently executing agent.

fn user_id(&self) -> &str

Returns the user identifier for this session.

fn app_name(&self) -> &str

Returns the application name for this session.

fn session_id(&self) -> &str

Returns the session identifier.

fn branch(&self) -> &str

Returns the current conversation branch.

fn user_content(&self) -> &Content

Returns the user’s input content for this invocation.

fn try_app_name(&self) -> Result<AppName, AdkError>

Returns the application name as a typed AppName.

fn try_user_id(&self) -> Result<UserId, AdkError>

Returns the user identifier as a typed UserId.

fn try_session_id(&self) -> Result<SessionId, AdkError>

Returns the session identifier as a typed SessionId.

fn try_invocation_id(&self) -> Result<InvocationId, AdkError>

Returns the invocation identifier as a typed InvocationId.

fn try_identity(&self) -> Result<AdkIdentity, AdkError>

Returns the stable session-scoped AdkIdentity triple.

fn try_execution_identity(&self) -> Result<ExecutionIdentity, AdkError>

Returns the full per-invocation ExecutionIdentity.