Struct AgentCtx 

pub struct AgentCtx<'a> { /* private fields */ }

Handed to an AgentHandler::handle so it can reply, send, request, or fan out without holding Laser itself. Causality (conversation_id, causal_parent, root) is wired automatically off the message being handled.

Implementations

impl<'a> AgentCtx<'a>

pub fn request_at(&self) -> Option<LogPosition>

Where the handled record sits on the log, when the runtime knows it.

pub fn laser(&self) -> &Laser

The Laser handle, for operations the ctx helpers do not cover (kv, query, …).

pub fn message(&self) -> &AgentMessage

The message currently being handled.

pub fn session(&self) -> Session

The session of the handled record, written as this agent and acting on the handled record: graph writes take it as source and remembered items as origin. A lens only: it holds no lease and starts no heartbeat. Its pending_control reports the pause and cancel requests the runtime observed.

pub async fn respond( &self, payload: impl Into<Vec<u8>>, ) -> Result<(), LaserError>

Reply on the agent’s configured respond_on topic, chaining causality (causal_parent = this message) and routing back to its sender. Errors with NoRespondTopic if the agent was built without respond_on.

An agent built with a signing key answers a correlated command with a signed AGDX response instead, so a verifying caller (and the contract path’s signer binding) accepts this agent’s terminal and no one else’s.

pub async fn reply_on( &self, topic: AgentTopic<'_>, payload: impl Into<Vec<u8>>, ) -> Result<(), LaserError>

A reply provenance for topic, chained off this message. The caller sets routing and usage as needed. Useful when replying somewhere other than respond_on.

pub async fn send( &self, topic: AgentTopic<'_>, payload: impl Into<Vec<u8>>, provenance: &Provenance, ) -> Result<(), LaserError>

Send payload to topic with an explicit provenance (no automatic causality).

pub async fn request( &self, request_topic: AgentTopic<'_>, reply_topic: AgentTopic<'_>, payload: impl Into<Vec<u8>>, provenance: &Provenance, timeout: Duration, ) -> Result<AgentMessage, LaserError>

Send a request and await its correlated reply (see Laser::request).

pub async fn respond_input( &self, reply_topic: AgentTopic<'static>, response: impl Into<Vec<u8>>, ) -> Result<(), LaserError>

Resolve the human-in-the-loop interrupt being handled: publish an AGDX response on reply_topic carrying the handled command’s interrupt correlation, so the paused Agdx::request_input caller resumes with response. The pairing is the correlation, so the reply reaches the right waiter even when several share reply_topic. An agent built with a signing key signs the response, so a verifying interrupt caller accepts this agent’s decision and no one else’s. Errors if the handled message is not an AGDX envelope carrying a correlation, or the agent was built without an id.

pub async fn approval_gate( &self, reply_topic: AgentTopic<'_>, prompt: impl Into<Vec<u8>>, timeout: Duration, ) -> Result<Vec<u8>, LaserError>

Pause this handler on a human decision: publish prompt as an interrupt on the human-input topic and await the approver’s correlated reply on reply_topic, up to timeout, chained to the handled conversation. Returns the decision body on approval, or LaserError::Rejected when the approver rejects (the approver answers with respond_input). A convenience over Agdx::request_input, so it adds nothing to the wire. Errors if the agent was built without an id.

pub fn spawn_subconversation(&self) -> Result<Provenance, LaserError>

A child conversation of the handled message, linked by parent/root ids.

pub async fn fan_out( &self, selector: CapabilitySelector, payload: impl Into<Vec<u8>>, policy: GatherPolicy, deadline: Duration, ) -> Result<Gather, LaserError>

Fan out to every agent advertising selector’s skill, gathering replies under policy within deadline. Each branch is a sub-conversation routed to one agent’s own inbox, resolved through the ctx’s InboxRoute (the per-agent live-presence inbox by default, or a fixed topic the caller set at build time), never a shared topic name baked into the SDK. Replies are collected on the orchestrator’s own response topic (respond_on), so a deployment that scopes each user to its own stream and each workflow to its own topic routes correctly.

A target that resolves no inbox (advertised none, or refresh_presence surfaced none) is a per-branch Gather::failures entry, never silently rerouted. Under GatherPolicy::Quorum the remaining branches are dropped once the quorum lands rather than waited on (signing a cancel to the losing branches on the control channel is a follow-on). Errors only on an infrastructure failure (no capable agent, no response topic, registry read), not on a branch failure.