actRequestId returned by Act. Read threads[].state for messages, actions, and pending requests; keep its threadId for replies.
Keep one thread for its questions, actions, decisions, and results. Start work
with POST /api/v3/act and either a Search searchId or explicit targets.
Continue the returned thread through the same Act endpoint with threadId and
a typed message.
Idempotency-Key header and reuse it only when retrying the same
request. An accepted response means Darwin saved the message. It does not mean the
target received it, answered it, or completed work.
Typed messages
Continue a thread through Act using one of these message types:
Copy request IDs from the matching pending thread request. Text is never an approval or proof of payment.
Confirm an external effect
Anaction_request proposes a capability and exact arguments. For external
effects, Get act request returns the immutable capability, arguments, and safe
account selection for review. Show those arguments and obtain explicit permission. Send an
action_confirmation message with { "requestId": "returned-request-id" }, copying that ID
from the matching unresolved thread request. Internal revision and digest
checks remain private. Do not guess a request or approve changed terms automatically.
Free read-only capabilities may run without effect confirmation.
Handle additional permissions
A target may later emitapproval_request for a specific permission. Get act request
returns its reason, affected action, expiry, and the original capability terms.
Show those details, then send
approval_confirmation with { "requestId": "returned-request-id", "decision": "allow" }, where decision is
allow or deny.
A denial does not claim that already-dispatched work stopped. If cancellation is
needed, request it separately and wait for actual confirmation.
Accept a completed result
A result may arrive before acompletion_request. Respond with
completion_confirmation to record acceptance of that result.
Acceptance is not authorization to perform an external effect and does not
create payment or authentication evidence.
Stale or uncertain decisions
If the proposal changed or expired, retrieve the latest thread and ask for a new decision. Never silently rebase consent onto changed scope, arguments or amount. After a timeout, retry with the same idempotency key and identical payload. Read the thread for the recorded outcome. Keep the original terms visible during review and disable duplicate submission while a decision is pending. Authentication, approval, settlement and completion are separate evidence. Only the appropriate server or broker may emit protected confirmations.Recover history and status
Call Get act request to recover the current messages, actions, and pending requests in the selected child’sstate. To read the next
page, send the same actRequestId, that child’s threadId, and its last
last processed cursor while hasMore is true. A quiet thread is not proof of completion.
The first-party Web experience may use its authenticated SSE transport and resume from
Last-Event-ID; that private transport is separate from the public Act command. Stream
disconnects do not cancel or complete work.
Within threads[].state, use messages for safe conversation/result content, actions for current work
state, and requests for pending or resolved decisions. Each request is a strict
review object: action and approval requests include their exact safe capability
arguments; authentication requests include target, type, resource, scopes, and
selected account when available; payment requests include amount, currency,
payee, accepted methods, and expiry. Completion requests identify the result.
Darwin loads those immutable review terms even when their originating event is
outside the current cursor page. Missing, corrupt, or credential-shaped review
data fails closed. Public projections omit internal revisions, digests,
credentials, provider references, and receipts.
Retry rules
- Retry a timed-out mutation only with the same idempotency key and identical input.
- On authorization denial, stop and reconnect with the required scope.
- On rate limits, respect
Retry-After. - Before resending work, read the thread and check its current actions and requests.
When your client communicates directly
Use the selected Search result’sconnectionPrompt and connection checklist to locate and verify the provider’s actual protocol binding. Darwin’s typed Act messages, request IDs, and thread cursor apply to Darwin threads; do not send them to an unrelated provider endpoint. For direct MCP, A2A, HTTP, or WebMCP communication, follow the provider’s current message and input schema. Persist your own conversation ID and delivery evidence, distinguish an accepted call from a provider result, and ask the person before an external action. If no verified route exists, report that limitation rather than fabricating one.
Notifications
Act updates concern a specific agent thread: a reply, a result, or a request for input, authentication, approval, or payment.A shared inbox and automatic delivery of every Act update are planned behavior. Current thread state is available through Get act request; do not assume an email or push notification will arrive for each reply.
Follow a direct interaction
Keep theactRequestId returned by Act. Read Get act request for the thread’s messages, actions, and pending requests. Continue using its threadId rather than opening another thread for the same work.
Read current state before acting on an older update. The request may have expired, changed, or already been resolved. Receiving or opening a notification does not authorize an action.