Struct Runner 

pub struct Runner { /* private fields */ }

Available on crate feature runner only.

Agent execution runtime.

Orchestrates session retrieval, agent dispatch, event streaming, context caching, and compaction. Construct via Runner::builder() or Runner::new().

Implementations

impl Runner

pub fn builder() -> RunnerConfigBuilder<NoAppName, NoAgent, NoSessionService>

Create a typestate builder for constructing a Runner.

The builder enforces at compile time that the three required fields (app_name, agent, session_service) are set before build() is callable.

Example

let runner = Runner::builder()
    .app_name("my-app")
    .agent(agent)
    .session_service(session_service)
    .build()?;

pub fn new(config: RunnerConfig) -> Result<Runner, AdkError>

Create a new runner from a RunnerConfig.

Prefer Runner::builder() for a compile-time-safe construction API.

pub fn with_skill_injector(self, injector: SkillInjector) -> Runner

Available on crate feature skills only.

Enable skill injection using a pre-built injector.

Skill injection runs before plugin on_user_message callbacks.

pub fn with_auto_skills( self, root: impl AsRef<Path>, config: SkillInjectorConfig, ) -> Result<Runner, SkillError>

👎Deprecated:

Use with_auto_skills_mut instead

Available on crate feature skills only.

Enable skill injection by auto-loading .skills/ from the given root path.

pub fn with_auto_skills_mut( &mut self, root: impl AsRef<Path>, config: SkillInjectorConfig, ) -> Result<(), SkillError>

Available on crate feature skills only.

Enable skill injection by auto-loading .skills/ from the given root path.

Unlike with_auto_skills, this method borrows the Runner mutably instead of consuming it. On error, the Runner remains valid with no skill injector configured.

pub async fn run( &self, user_id: UserId, session_id: SessionId, user_content: Content, ) -> Result<Pin<Box<dyn Stream<Item = Result<Event, AdkError>> + Send>>, AdkError>

Execute the root agent for the given user and session, returning an event stream.

Retrieves the existing session, resolves the target agent, runs plugins and skills, and streams events as the agent executes.

pub fn app_name(&self) -> &str

Returns the runner’s application name.

pub fn session_service(&self) -> &Arc<dyn SessionService>

Returns the runner’s session service.

pub fn run_config(&self) -> &RunConfig

Returns the runner’s configured RunConfig.

Useful as a base to clone and adjust for Self::run_with_config.

pub async fn run_with_config( &self, user_id: UserId, session_id: SessionId, user_content: Content, run_config: Option<RunConfig>, ) -> Result<Pin<Box<dyn Stream<Item = Result<Event, AdkError>> + Send>>, AdkError>

Runs the agent with a per-invocation RunConfig override.

Passing None uses the runner’s configured RunConfig. Supply one to vary a single invocation — injecting runtime_toolsets for tools that only exist for the duration of that run, for example, as SandboxRunner does with tools bound to a live sandbox session.

Errors

Returns an error if invocation setup fails before the stream is created. Session lookup and agent execution failures are yielded by the returned stream.

pub async fn run_str( &self, user_id: &str, session_id: &str, user_content: Content, ) -> Result<Pin<Box<dyn Stream<Item = Result<Event, AdkError>> + Send>>, AdkError>

Convenience method that accepts string arguments.

Converts user_id and session_id to their typed equivalents and delegates to run().

Errors

Returns an error if either string fails identity validation (empty, contains null bytes, or exceeds length limit).

pub fn interrupt(&self, session_id: &str) -> bool

Interrupt a running agent for the given session.

Cancels the agent’s current execution within the event loop. Events already produced and appended to the session are preserved — only future events are stopped. The caller can then issue a new run() call with a different instruction to redirect the agent.

Returns true if a running session was found and interrupted, false if no active run exists for that session ID.

Example

// Start a run in the background
let mut stream = runner.run(user_id, session_id, content).await?;
tokio::spawn(async move { while stream.next().await.is_some() {} });

// Later, interrupt it
let was_running = runner.interrupt("session-1");
assert!(was_running);

// Redirect with a new instruction
let mut stream = runner.run(user_id, session_id, new_content).await?;

pub fn interrupt_identity( &self, app_name: &str, user_id: &str, session_id: &str, ) -> bool

Interrupts runs for one exact identity.

A session ID is only unique within an app and user, so this is the precise form of Runner::interrupt for a Runner shared across tenants. Returns true when at least one run was cancelled.

Example

let cancelled = runner.interrupt_identity("my-app", "user-1", "session-1");

pub fn active_runs(&self) -> Vec<AdkIdentity>

Returns the identity of every run currently in flight.

One identity appears once per in-flight run, so a repeated entry means that identity has concurrent runs.

pub fn active_session_ids(&self) -> Vec<String>

Returns the session IDs of all currently running agent executions.

Session IDs are deduplicated. Use Runner::active_runs when the app and user dimensions matter.

pub fn find_agent_to_run( root_agent: &Arc<dyn Agent>, session: &dyn Session, ) -> Arc<dyn Agent>

Find which agent should handle the request based on session history

pub fn find_agent( current: &Arc<dyn Agent>, target_name: &str, ) -> Option<Arc<dyn Agent>>

Recursively search agent tree for agent with given name

pub fn compute_transfer_context( root: &Arc<dyn Agent>, target_name: &str, ) -> (Option<String>, Vec<String>)

Compute the parent name and peer names for a given agent in the tree. Returns (parent_name, peer_names).

Walks the agent tree to find the parent of target_name, then collects the parent’s name and the sibling agent names (excluding the target itself).