AgentMessage
API reference
EXPERIMENTAL: Agent APIs are likely to change.
A message delivered to an agent's mailbox.
Implements Node
delivery: AgentMessageDelivery!Experimental
How the message conclusively landed: opened a new turn (STARTED), was absorbed into the running turn at a step boundary (STEERED), or queued behind it (QUEUED).
Blocks until provider or native lifecycle evidence is conclusive. Once recorded, the result or cancellation error is immutable.
Experimental: Agent APIs are likely to change.
id: ID!
A unique identifier for this AgentMessage.
ref: String!Experimental
The message's short ref within the receiving agent's runtime, e.g. "#3".
This is the deterministic token the recipient's attribution header shows and a reply's replyTo names — quote it when telling the recipient what to answer.
Experimental: Agent APIs are likely to change.
response: String!Experimental
Block until this message is answered, and return the answer: an explicit reply (a send whose replyTo names this message), or the final reply of the turn that consumed it, whichever comes first.
Idempotent: cancel and request the response again freely; concurrent waiters share the result.
Fails if the agent stops before the message resolves. On a failed agent it projects the failure — but the message stays pending, so after a resume consumes it, requesting the response again returns the real reply.
Refused when called from inside an agent turn whose wait would deadlock: turns should not block on other agents — send without awaiting, and the reply arrives as a message.
Experimental: Agent APIs are likely to change.