Struct Agent 

pub struct Agent {
    pub proc: Option<Arc<DaggerSessionProc>>,
    pub selection: Selection,
    pub graphql_client: DynGraphQLClient,
}

Fields

proc: Option<Arc<DaggerSessionProc>>

selection: Selection

graphql_client: DynGraphQLClient

Implementations

impl Agent

pub async fn error(&self) -> Result<String, DaggerError>

Why the loop failed, for a FAILED agent; empty otherwise. The snapshot holds the completed prefix — send or resume retries from it.

pub async fn handle(&self) -> Result<String, DaggerError>

The opaque runtime handle minted by the spawn that created this agent. It is the same value the agent’s loop span publishes as dagger.io/agent.id, so a client can correlate the agent with what it discovers in the trace. Two spawns of an identical composition have different handles; a display name is shared freely.

pub async fn id(&self) -> Result<Id, DaggerError>

A unique identifier for this Agent.

pub fn message(&self, ref: impl Into<String>) -> AgentMessage

Look up a previously sent message by its ref. This is the lookup send pins its result’s identity through: the returned handle’s ID is an honest, replayable chain, addressable from any request in the session (the cancel-and-request-again contract). Fails if the agent has no runtime entry in this session, or no record of the given ref.

Arguments

• r#ref - The message’s short ref within this agent’s runtime, e.g. “#3”: the token its attribution header shows and a reply’s replyTo names. A bare ordinal (“3”) is accepted too.

pub async fn name(&self) -> Result<String, DaggerError>

Display label for the agent; carries no identity.

pub async fn notify( &self, subscriber: impl IntoID<Id>, ) -> Result<Agent, DaggerError>

Subscribe another agent to this agent’s lifecycle: each transition into one of the given states enqueues an event message to the subscriber — steering its open turn, or waking it if idle, like any other message. This is how a supervisor hears every completion and failure without polling or blocking: subscribe at spawn time, keep working, and events arrive as attributed messages. Events never relaunch a stopped subscriber, and an already-reached state fires immediately at subscribe time, so a fast agent settling before the subscription lands is not missed. Idempotent per subscriber; re-subscribing replaces the state set.

Arguments

• subscriber - The agent to deliver event messages to. You must hold its handle: subscriptions are capability-based like everything else.
• opt - optional argument, see inner type for documentation, use _opts to use

pub async fn notify_opts( &self, subscriber: impl IntoID<Id>, opts: AgentNotifyOpts, ) -> Result<Agent, DaggerError>

Subscribe another agent to this agent’s lifecycle: each transition into one of the given states enqueues an event message to the subscriber — steering its open turn, or waking it if idle, like any other message. This is how a supervisor hears every completion and failure without polling or blocking: subscribe at spawn time, keep working, and events arrive as attributed messages. Events never relaunch a stopped subscriber, and an already-reached state fires immediately at subscribe time, so a fast agent settling before the subscription lands is not missed. Idempotent per subscriber; re-subscribing replaces the state set.

Arguments

• subscriber - The agent to deliver event messages to. You must hold its handle: subscriptions are capability-based like everything else.
• opt - optional argument, see inner type for documentation, use _opts to use

pub async fn pause(&self) -> Result<Agent, DaggerError>

Stop draining the mailbox once the in-flight step completes, or immediately with interrupt. Pause takes priority over pending work: a mid-turn pause suspends the turn, which resume continues. Messages sent while paused enqueue with QUEUED delivery until a resume. Pausing a never-started agent leaves it paused for its eventual resume; pausing a failed agent is allowed (resume decides the retry); pausing a stopped agent fails.

Arguments

• opt - optional argument, see inner type for documentation, use _opts to use

pub async fn pause_opts( &self, opts: AgentPauseOpts, ) -> Result<Agent, DaggerError>

Stop draining the mailbox once the in-flight step completes, or immediately with interrupt. Pause takes priority over pending work: a mid-turn pause suspends the turn, which resume continues. Messages sent while paused enqueue with QUEUED delivery until a resume. Pausing a never-started agent leaves it paused for its eventual resume; pausing a failed agent is allowed (resume decides the retry); pausing a stopped agent fails.

Arguments

• opt - optional argument, see inner type for documentation, use _opts to use

pub async fn reseed( &self, conversation: impl IntoID<Id>, ) -> Result<Agent, DaggerError>

Replace this instance’s committed conversation with the given one, keeping the entry: identity, mailbox, and lifecycle state are untouched. A paused suspended turn is abandoned and its consumed messages are resolved before replacement. This is the continuity verb. Compaction, a workspace rebind, a model change, or rewinding an interrupted prompt produce a new conversation value for the SAME agent; reseed swaps it in place, where a stop-and-respawn would mint a successor instance and split the agent across two roster entries. It is the client-facing form of what a continuation tool already does mid-turn: the agent adopts a new conversation without changing who it is. The next turn continues from the reseeded conversation, and queued messages drain onto it. A FAILED agent keeps its error — resume retries from the new conversation. Fails if the instance has no runtime entry in this session (only a spawned or re-hydrated instance holds a conversation to replace), if a step is in flight, or if the agent is stopped.

Arguments

• conversation - The conversation that becomes the agent’s committed history, replacing the current one.

pub async fn resume(&self) -> Result<Agent, DaggerError>

Resume draining the mailbox: a suspended turn continues from the last committed step, and queued messages drain. Resuming a never-started agent starts its evaluation loop, detached from the calling request: it steps the conversation while input is pending, then idles awaiting further lifecycle operations. Resuming a FAILED agent retries its pending step. Resuming a STOPPED agent relaunches the same instance from its last committed snapshot. No-op on a running or idle agent.

pub async fn send( &self, message: impl Into<String>, ) -> Result<AgentMessage, DaggerError>

Enqueue a message, on the record: it is consumed at a step boundary, appends to the agent’s history, and steers the running turn or opens a new one. Never blocks, never drops; concurrent sends queue in order. The returned message is pinned through the message lookup field, so its handle is re-addressable from any request in the session: cancel a response request and request it again freely. Sending to a never-started agent starts it (signal-with-start). Sending to a stopped agent restarts the same instance from its last committed snapshot. Sending to a paused or failed agent enqueues with QUEUED delivery, to be drained by a resume.

Arguments

• message - The message text, appended to the agent’s history as a prompt when a turn consumes it.
• opt - optional argument, see inner type for documentation, use _opts to use

pub async fn send_opts<'a>( &self, message: impl Into<String>, opts: AgentSendOpts<'a>, ) -> Result<AgentMessage, DaggerError>

Enqueue a message, on the record: it is consumed at a step boundary, appends to the agent’s history, and steers the running turn or opens a new one. Never blocks, never drops; concurrent sends queue in order. The returned message is pinned through the message lookup field, so its handle is re-addressable from any request in the session: cancel a response request and request it again freely. Sending to a never-started agent starts it (signal-with-start). Sending to a stopped agent restarts the same instance from its last committed snapshot. Sending to a paused or failed agent enqueues with QUEUED delivery, to be drained by a resume.

Arguments

• message - The message text, appended to the agent’s history as a prompt when a turn consumes it.
• opt - optional argument, see inner type for documentation, use _opts to use

pub fn snapshot(&self) -> Llm

The conversation as of the last committed step: immutable, branchable, persistable. The seed conversation if the agent never stepped. Branching from it does not affect the agent.

pub async fn state(&self) -> Result<AgentState, DaggerError>

Computed lifecycle state; never stored. An agent that was never started reports IDLE: its mailbox is empty and no turn is open.

pub async fn stop(&self) -> Result<Agent, DaggerError>

Release the agent’s runtime. The tombstone (state, snapshot) stays readable for the rest of the session.

Arguments

• opt - optional argument, see inner type for documentation, use _opts to use

pub async fn stop_opts(&self, opts: AgentStopOpts) -> Result<Agent, DaggerError>

Release the agent’s runtime. The tombstone (state, snapshot) stays readable for the rest of the session.

Arguments

• opt - optional argument, see inner type for documentation, use _opts to use

pub async fn wait(&self) -> Result<Agent, DaggerError>

Block until the agent settles: IDLE, FAILED, or STOPPED. Read which from state afterwards. Unlike waiting for one exact state, this cannot hang merely because the agent settled in a different outcome.

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Agent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl IntoID<Id> for Agent

fn into_id( self, ) -> Pin<Box<dyn Future<Output = Result<Id, DaggerError>> + Send>>

impl Loadable for Agent

fn graphql_type() -> &'static str

The GraphQL type name (e.g. "Container").

fn from_query( proc: Option<Arc<DaggerSessionProc>>, selection: Selection, graphql_client: DynGraphQLClient, ) -> Self

Construct this type from a query selection.

impl Node for Agent

fn id(&self) -> impl Future<Output = Result<Id, DaggerError>> + Send