Agent
API reference
EXPERIMENTAL: Agent APIs are likely to change.
A conversation loop running as an addressable, long-lived entity within the session. The conversation itself remains observable at any time as an immutable LLM value.
Implements Node
error- Why the loop failed, for a FAILED agent; empty otherwise.
handle- The opaque runtime handle minted by the spawn that created this agent.
id- A unique identifier for this Agent.
name- Display label for the agent; carries no identity.
state- Computed lifecycle state; never stored.
message- Look up a previously sent message by its ref.
notify- 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.
pause- Stop draining the mailbox once the in-flight step completes, or immediately with interrupt.
reseed- 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.
resume- Resume draining the mailbox: a suspended turn continues from the last committed step, and queued messages drain.
send- 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.
snapshot- The conversation as of the last committed step: immutable, branchable, persistable.
stop- Release the agent's runtime. The tombstone (state, snapshot) stays readable for the rest of the session.
wait- Block until the agent settles: IDLE, FAILED, or STOPPED. Read which from state afterwards.
error: String!Experimental
Why the loop failed, for a FAILED agent; empty otherwise.
The snapshot holds the completed prefix — send or resume retries from it.
Experimental: Agent APIs are likely to change.
handle: String!Experimental
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.
Experimental: Agent APIs are likely to change.
id: ID!
A unique identifier for this Agent.
name: String!Experimental
Display label for the agent; carries no identity.
Experimental: Agent APIs are likely to change.
state: AgentState!Experimental
Computed lifecycle state; never stored.
An agent that was never started reports IDLE: its mailbox is empty and no turn is open.
Experimental: Agent APIs are likely to change.
message(ref: String!): AgentMessage!Experimental
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.
Experimental: Agent APIs are likely to change.
ref: String!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.
notify(subscriber: Agent!, on: [AgentState!] = [IDLE, FAILED]): Agent!Experimental
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.
Experimental: Agent APIs are likely to change.
subscriber: Agent!The agent to deliver event messages to. You must hold its handle: subscriptions are capability-based like everything else.
on: [AgentState!] = [IDLE, FAILED]The lifecycle states that fire an event. IDLE events carry the turn's final reply; FAILED events carry the loop error.
pause(interrupt: Boolean = false): Agent!Experimental
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.
Experimental: Agent APIs are likely to change.
interrupt: Boolean = falsePreempt the in-flight step instead of letting it finish. All completed steps are kept and the interrupted turn stays open: messages it consumed remain pending, while unconsumed mailbox messages are discarded. Resume continues the turn from the last committed step. On an idle, never-started, or failed agent there is nothing to preempt, so this is a plain pause.
reseed(conversation: LLM!): Agent!Experimental
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.
Experimental: Agent APIs are likely to change.
conversation: LLM!The conversation that becomes the agent's committed history, replacing the current one.
resume: Agent!Experimental
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.
Experimental: Agent APIs are likely to change.
send(message: String!, replyTo: String = ""): AgentMessage!Experimental
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.
Experimental: Agent APIs are likely to change.
message: String!The message text, appended to the agent's history as a prompt when a turn consumes it.
replyTo: String = ""The ref of a message in the SENDER's own mailbox this send answers (e.g. "#3", from its attribution header). The recipient sees the two paired, and awaiters of the replied-to message resolve with this reply immediately instead of at the sender's turn end.
snapshot: LLM!Experimental
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.
Experimental: Agent APIs are likely to change.
stop(kill: Boolean = false): Agent!Experimental
Release the agent's runtime. The tombstone (state, snapshot) stays readable for the rest of the session.
Experimental: Agent APIs are likely to change.
kill: Boolean = falseCancel the loop immediately instead of letting an in-flight step finish. Either way the completed steps are preserved in the snapshot.