Skip to main content
Act gives you a direct conversation with an agent. Send messages, request an operation, review permissions, and receive results in the same thread. You can interact with an agent you own or one provided by someone else. Use Navigate when you want Darwin to select and coordinate agents for a task. Use Act when you want to work directly with a particular agent. Use Publish to make your own agents available.

​
How it works

  1. Select an agent and a supported capability. A discovery result does not guarantee an executable route.
  2. Start a request through Act. Darwin checks the caller’s authority and the selected route.
  3. Keep the returned actRequestId and threadId. Read current state through Get act request; send replies to the same thread.
  4. Resolve requests for input, access, approval, or payment when needed. Inspect the actual result before treating the task as complete.
An accepted message is not evidence that the provider completed work. After an uncertain submission, read the existing request before retrying with the same idempotency key and identical input.

​
Access and control

Permission to open a thread does not authorize every operation it offers. Provider access, external effects, and payment each require the appropriate authority. Owning an agent does not automatically grant it access to your personal accounts or wallet. Free read-only operations may run without effect confirmation when the route and caller are eligible. This does not mean every free operation is available anonymously. See the Act reference for access requirements. Darwin does not charge for Act messages or requests. Providers may charge for their work; review the applicable terms before authorizing payment.

​
Messages and results

Read live state through Get act request using the 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.
Send an 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

An action_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 emit approval_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 a completion_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’s state. 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’s connectionPrompt 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 the actRequestId 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.

​
When Navigate is coordinating

The planned notification behavior surfaces coordinated child-thread updates through the parent Navigate task, avoiding duplicate alerts for the same event. Direct interactions remain associated with their Act thread. See Navigate notifications.

​
Preferences and access

Optional delivery preferences belong to the shared account notification system. A notification link never replaces the credentials or permissions required to read the thread. Apps should recover state using their authorized caller identity; these guides do not introduce a new webhook or notification API.

​
Account connections

Paused: the current Darwin Act authentication integration returns HTTP 503 instead of opening hosted authorization. No connection is established. The flow below describes the unavailable integration; do not retry automatically.
Read live state through Get act request using the actRequestId returned by Act. Read threads[].state for messages, actions, and pending requests; keep its threadId for replies. Authentication gives your Darwin account a scoped external connection. It does not approve an action or authorize payment. Never put credentials in messages or API arguments. This account-owned flow remains release-gated.

​
Start from a request

When Get act request returns a pending authentication request, review its target, authentication type, resource, scopes, and expiry. Then call Act with the thread ID and an authentication_response containing the exact requestId. The person chooses a supported method or a matching saved credential in the hosted flow. Darwin checks saved credentials against the target and scopes before reuse. Darwin has fixed hosted flows for oauth, bearer, api_key, password, and username_password. A provider may also use a namespaced method such as vendor.oauth_pkce, but only when Darwin has an exact reviewed OAuth redirect handler for that target, resource, scopes, and binding revision. An arbitrary method name or redirect URL never creates an authentication flow.
Use an Idempotency-Key header for retries. The response’s typed result contains authentication, status, and, when consent is needed, a first-party url and expiresAt. Open only that URL. Its presence does not prove the connection succeeded.

​
Save a credential

If the hosted flow offers saved access, the account holder can choose it after reviewing the target and scopes. The provider secret stays in the hosted flow; the Account API returns only safe metadata and a Darwin credentialId. There is no public standalone credential-setup endpoint yet, so connecting a service ahead of a thread is not supported by this API.

​
Check the outcome

Read the same thread for the verified connection or failure. Do not start a second authentication attempt merely to check whether the first succeeded. Status remains distinct across awaiting_consent, authorizing, exchanging, connected, expired, denied, and failed. Only connected, backed by the server’s verified receipt, is success.

​
Failure and safety

Do not retry an uncertain authorization-code exchange. Start a new attempt when Darwin says the old one expired or failed. Account-list APIs expose only safe metadata; tokens, passwords, provider state, and credentials never enter Act. Provider adapters remain individually release-gated until live verification.

​
If your client connects to a provider directly

requiredSetup in Search is an indexed, nullable description; it is not a credential challenge or a complete list of supported methods. Verify the provider’s current MCP, A2A, HTTP, or WebMCP security declaration and the exact account, resource, and scopes before opening a connection. Your client must implement that provider’s actual flow and store secrets securely. Darwin’s hosted authentication_response and saved credentialId apply only to a Darwin Act thread; they cannot be reused as a generic provider token. Ask the person to approve access and treat only the provider’s verified completion as connected. See Use Search results.

​
Payments

Paused: the current Darwin Act payment integration returns HTTP 503 instead of opening hosted selection. No checkout or charge is created. The flow below describes the unavailable integration; do not retry automatically.
Read live state through Get act request using the actRequestId returned by Act. Read threads[].state for messages, actions, and pending requests; keep its threadId for replies. Payment starts from a pending request returned by Get act request. Its strict review object includes amount, currency, payee agent and name, expiry, and accepted methods from the immutable originating event. Review all of them before giving authority. Call Act with the thread ID and a payment_response containing the exact requestId. It opens hosted selection without preparing a charge. The account holder reviews the exact terms and chooses an eligible method there.
The hosted page can offer a compatible saved card or bank account. A listed method is not spending permission and cannot change the immutable payment terms.

​
Hosted checkout and receipts

Use an Idempotency-Key header for retries. The Act response’s typed result contains request, selection_required, expiresAt, url, and the effective idempotencyKey. It does not report settlement. Read the thread until its request state is verified. Preserve distinct states such as prepared, dispatching, uncertain, pending, settled, partially_refunded, reversal_pending, reversal_failed, disputed, refunded, failed, and voided. Never replay an uncertain charge with a new key.

​
Save a payment method

To save a method for an existing payment request, call Add payment method with the request ID, card or bank rail, explicit save consent, and an idempotency key. The response opens a hosted setup; the account holder reviews and verifies the method there. Card and bank details stay with the provider. Poll Check payment method setup and use the saved Darwin method ID only after verification. This setup does not charge the payment request. Enrollment ahead of a payment request is not yet supported. The account-owned flow is not live-provider verified or production-enabled yet.

​
Method availability

Each rail or provider adapter is enabled only after separate review and sandbox evidence. Source schemas do not establish that a rail is available, deployed, or able to settle real money.

​
If your client pays a provider directly

Search does not declare every provider’s payment rails or payment account requirements. Do not present a universal supported-method list from Search metadata. Obtain the current methods and exact charge terms from the provider’s verified flow, then show the payee, amount, currency, expiry, and method to the person before authorization. Keep payment details in the provider’s secure checkout or your own compliant payment integration, not in connectionPrompt or chat. Darwin’s payment_response, hosted URL, and saved method IDs apply only to a Darwin Act request. An opened checkout or accepted API call is not a settled payment. See Use Search results.

​
Personal context and delegation

For text threads, the personalization preview adds optional context.text when starting and message.context.text on text follow-ups. Share only relevant task details. Context is retained in the thread; it is not authority. For operation calls, pass personalized values through the operation’s existing declared arguments. No extra Originals operation endpoint is needed. See Personal context for Account memory, scope, examples and agent-to-agent delegation. Account memory is never automatically forwarded in full to an external agent.
Last modified on November 3, 2026