Struct Agent 

pub struct Agent { /* private fields */ }

Stable public entry point for agent execution.

Wraps an AgentRuntime and provides:

• Agent::execute() — run the agent loop on a session
• Agent::storage() — access the shared storage backend

Clone is cheap (inner is Arc).

Implementations

impl Agent

pub fn from_runtime(runtime: Arc<AgentRuntime>) -> Self

Wrap an existing AgentRuntime in an Agent.

pub fn builder() -> AgentBuilder

Return a new builder.

pub async fn execute( &self, session: &mut Session, req: ExecuteRequest, ) -> Result<()>

Execute the agent loop with the given request.

pub async fn execute_with_upstream_retry( &self, session: &mut Session, req: ExecuteRequest, upstream_retry: UpstreamRetry, ) -> Result<()>

Execute with an explicit initial upstream request policy.

pub async fn execute_with_inputs( &self, session: &mut Session, req: ExecuteRequest, inputs: Option<UntrustedExecutionInputs>, ) -> Result<()>

Explicit bounded caller-data handoff; no currentness or Skill authority. Ordinary execute/direct/spawn entrypoints continue to supply None.

pub async fn execute_direct( &self, session: &mut Session, req: ExecuteRequest, ) -> Result<()>

Execute a caller-owned session under a complete logical-session activation lifecycle.

Server/child entry points already own an external runner reservation and therefore use execute plus their existing terminal handshake. Direct SDK callers have no runner registry, so this wrapper registers the current run before entering the provider loop, marks it finalizing immediately after return, migrates any terminal-window legacy ingress, and lets the router reserve at most one successor for work the completed reasoning turn did not admit.

pub async fn execute_direct_with_upstream_retry( &self, session: &mut Session, req: ExecuteRequest, upstream_retry: UpstreamRetry, ) -> Result<()>

Execute through the direct owner lifecycle with an explicit retry policy.

pub fn check_direct_execution_admission<'a>( &'a self, session: &'a mut Session, lease: &'a DirectExecutionLease, ) -> impl Future<Output = Result<()>> + Send + 'a

Check counted-state admission under an already acquired opaque lease. SDK facades call this before Project preparation or approved-tool replay. This can refuse/fence an interrupted generation; it never replays it.

pub async fn prepare_external_session_for_execution( &self, session: &mut Session, ) -> Result<()>

Validate and publish Project/Workspace context for a caller-owned session before any external pre-execution side effect.

SDK facades that acquire a direct lease themselves call this before approved-tool replay. execute_direct also calls it, so the lower-level escape hatch cannot bypass legacy migration, Project validation, or runtime workspace publication.

pub async fn prepare_external_project_assignment_read_only( &self, session: &mut Session, ) -> Result<()>

Resolve a proposed SDK Project assignment without publishing a runtime workspace. The caller must persist the validated candidate before the ordinary execution handoff publishes it or replays an approved tool.

pub async fn begin_direct_execution( &self, target_session_id: &str, ) -> Result<DirectExecutionLease>

Acquire direct logical-session ownership before an SDK facade performs pre-execution work such as replaying an approved mutating tool.

pub async fn execute_direct_registered( &self, session: &mut Session, req: ExecuteRequest, lease: DirectExecutionLease, ) -> Result<()>

Execute and finalize a direct run whose ownership was acquired by begin_direct_execution.

pub async fn execute_direct_registered_with_inputs( &self, session: &mut Session, req: ExecuteRequest, lease: DirectExecutionLease, inputs: Option<UntrustedExecutionInputs>, ) -> Result<()>

Existing direct lifecycle with a separately owned, untrusted input handoff.

pub fn storage(&self) -> &Arc<dyn Storage>

Access the shared storage backend.

pub fn persistence(&self) -> &Arc<dyn RuntimeSessionPersistence>

Access the runtime persistence adapter for non-authoritative saves.

pub fn session_inbox(&self) -> Option<&Arc<dyn SessionInboxPort>>

pub async fn admit_session_inbox_at_safe_boundary( &self, session: &mut Session, ) -> usize

Execute the same durable SessionInbox boundary used by the agent loop before its first provider call. This compatibility method reports only the merge count; it cannot confirm successful ACK. Execution entry points must use Self::admit_session_inbox_at_safe_boundary_checked instead.

pub async fn admit_session_inbox_at_safe_boundary_checked( &self, session: &mut Session, ) -> Result<usize, AgentError>

Confirm the durable admission boundary before entering provider execution. An ACK error is unresolved even after receipt publication. Preserve the checkpoint and existing claim recovery, but reject this activation.

pub fn activation_router(&self) -> Option<&Arc<SessionActivationRouter>>

pub fn session_messenger(&self) -> Option<&Arc<SessionMessenger>>

pub fn default_tools(&self) -> &Arc<dyn ToolExecutor>

Access the runtime’s default tool executor (the root/full tool surface assembled at build time).

Exposed so callers can compose additional one-off dispatches against the SAME executor the loop itself uses — e.g. re-executing a single previously-gated tool call after a permission approval — without forking or reaching into AgentLoopConfig (which stays unconstructible outside the engine). This is a read-only accessor alongside storage() / persistence(); it does not touch the sealed loop config.

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.