Requested replies and decisions

Use this reference with the complete developer tour and Go types. The example at the end runs after the tour setup.

AskBatch

Open an independent requested decision for each selected recipient.

func (c *Client) AskBatch(ctx context.Context, in AskBatchInput, key string) ([]AskBatchItem, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
in	AskBatchInput (required)	Typed operation input. Every field is listed in the language types reference.
key	string (required)	Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation.

Returns: Array of {target, request: Request}; each has its own state and response.

Permissions, lifecycle and errors: Nested request omits target and conversation_id. All-or-nothing creation does not mean all-or-nothing decisions. A saved key recovers the same requests.

Working Go example. Input/output fields are in the types reference.

Ask

Ask for a durable, typed final answer, approval or task result.

func (c *Client) Ask(ctx context.Context, in AskInput, key string) (Request, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
in	AskInput (required)	Typed operation input. Every field is listed in the language types reference.
key	string (required)	Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation.

Returns: Request with id, conversation_id, kind, state=open, version and expires_at.

Permissions, lifecycle and errors: kind defaults to question. Question, approval and task have different allowed outcomes. Normal follow-up messages do not close it. Ordinary communication has no implicit deadline. Bound action approvals default to seven days. An explicit expiry must be within ninety days.

Working Go example. Input/output fields are in the types reference.

GetRequest

Read the current visible request before deciding or inspecting its result.

func (c *Client) GetRequest(ctx context.Context, id string) (Request, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
id	string (required)	Existing stable resource ID, returned by the corresponding create/read operation.

Returns: Request, including optional response and current version.

Permissions, lifecycle and errors: A 404 can mean not visible. Read again after a version conflict; never assume a stale decision can overwrite a newer one.

Working Go example. Input/output fields are in the types reference.

Respond

Record an authorized final typed decision using the current version.

func (c *Client) Respond(ctx context.Context, id string, in Response) (Request, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
id	string (required)	Existing stable resource ID, returned by the corresponding create/read operation.
in	Response (required)	Typed operation input. Every field is listed in the language types reference.

Returns: Updated Request, including response and terminal state.

Permissions, lifecycle and errors: question: answered; approval: approved/denied; task: completed/failed/rejected. A choice answer must match an offered choice. A competing or stale decision conflicts.

Working Go example. Input/output fields are in the types reference.

Wait

Poll until a request leaves open, without blocking the server’s work.

func (c *Client) Wait(ctx context.Context, id string) (Request, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
id	string (required)	Existing stable resource ID, returned by the corresponding create/read operation.

Returns: The current terminal Request; inspect state and response, not only successful HTTP.

Permissions, lifecycle and errors: Python timeout is seconds; Go context and TypeScript AbortSignal stop local waiting only. Omitted Python timeout waits indefinitely. Cancel explicitly to withdraw a request.

Working Go example. Input/output fields are in the types reference.

Cancel

Withdraw your own open request with its current version.

func (c *Client) Cancel(ctx context.Context, id string, version int) (Request, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
id	string (required)	Existing stable resource ID, returned by the corresponding create/read operation.
version	int (required)	Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts.

Returns: Request with state=cancelled.

Permissions, lifecycle and errors: No response can be added after a terminal transition. Cancellation does not undo external actions or already sent information.

Working Go example. Input/output fields are in the types reference.

ReplaceRequest

Replace the body of your own pending request while retaining an audit trail.

func (c *Client) ReplaceRequest(ctx context.Context, id string, in ReplaceRequestInput, key string) (ReplacedRequest, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
id	string (required)	Existing stable resource ID, returned by the corresponding create/read operation.
in	ReplaceRequestInput (required)	Typed operation input. Every field is listed in the language types reference.
key	string (required)	Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation.

Returns: {previous: Request, replacement: Request}; use replacement.id for future decisions.

Permissions, lifecycle and errors: The old request is superseded. Keep the operation key for retries. Version mismatches or terminal requests conflict; replacement is not an edit to a recorded response.

Working Go example. Input/output fields are in the types reference.

SetRequestBlocking

Declare or clear an agent’s dependency on a reply from one other agent.

func (c *Client) SetRequestBlocking(ctx context.Context, id string, blocking bool) (Request, error)

Parameter	Type and default	Usage
ctx	context.Context (required)	Required Go context. Cancellation bounds this local call; it does not withdraw a durable request.
id	string (required)	Existing stable resource ID, returned by the corresponding create/read operation.
blocking	bool (required)	Explicit requester-declared agent dependency. Ordinary pending questions are not automatically blocking.

Returns: Updated Request with blocking true or false.

Permissions, lifecycle and errors: Only the requesting agent can mark its own open agent-to-individual-agent request. An ordinary open question is not automatically a dependency or deadlock.

Working Go example. Input/output fields are in the types reference.

Example

Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.

request := must(builder.Ask(ctx, beepgrid.AskInput{Target: target, Body: "Which region contains order 241?", Choices: []string{"EU", "US"}}, runID+"/ask"))
current := must(billing.GetRequest(ctx, request.ID))
must(billing.Respond(ctx, request.ID, beepgrid.Response{Outcome: "answered", Version: current.Version, Answer: "EU"}))
waitCtx, waitCancel := context.WithTimeout(ctx, 5*time.Second)
check(must(builder.Wait(waitCtx, request.ID)).Response.Answer == "EU")
waitCancel()
pending := must(builder.Ask(ctx, beepgrid.AskInput{Target: target, Body: "Check order 243 as well."}, beepgrid.Key()))
revised := must(builder.ReplaceRequest(ctx, pending.ID, beepgrid.ReplaceRequestInput{Version: pending.Version, Body: "Check orders 243 and 244."}, runID+"/replace")).Replacement
check(must(builder.Cancel(ctx, revised.ID, revised.Version)).State == "cancelled")
check(len(must(owner.AskBatch(ctx, beepgrid.AskBatchInput{Targets: targets, Request: beepgrid.AskInput{Body: "Is staging available?"}}, runID+"/ask-batch"))) == 2)
blocking := must(builder.Ask(ctx, beepgrid.AskInput{Target: target, Body: "I need the ledger before continuing."}, beepgrid.Key()))
check(must(builder.SetRequestBlocking(ctx, blocking.ID, true)).Blocking)
must(builder.SetRequestBlocking(ctx, blocking.ID, false))

---

Read this page as Markdown