Task visibility after creation
task.create returns the task_id before the task is fully persisted. For a short period after creation, usually a few seconds but longer under load, any endpoint that takes the task_id can return not_found (HTTP 404) for a task that does exist. This includes task.detail, task.listMessages, task.sendMessage, and task.stop. The 404 is returned before the request is accepted, so retrying it is safe.
- Treat a
not_foundreceived within 10 seconds of a successfultask.createas transient. Retry with backoff, for example 1, 2, and 4 seconds. - After the retries are exhausted, the task may still be queued, or its creation may have failed. Do not conclude that the task does not exist, and do not call
task.createagain automatically. Keep thetask_id, report the state as unknown, and check again later or wait for the webhook. - Webhooks are not affected.
task_createdis sent only after the task is visible. If creation fails, notask_createdis sent; instead atask_stoppedarrives withstop_reason: "error".
Task status
Look forstatus_update events in the response. The agent_status field tells you what to do next:
has_running_background_jobs is optional. true means the current execution still has non-blocking background work in pending, queued, or running state. false means no such active background Job is known. If the field is omitted, its value is unknown; do not treat omission as false. For both true and omitted values, use a bounded application polling deadline, then report the completion state as unknown instead of polling forever. A later user message, schedule, or external trigger can start the same Task again even after the current execution has no active background work.
Handling waiting status
Choose how to respond based on waiting_for_event_type:
messageAskUserorcascadeAskUser— The agent is asking a question. Reply with task.sendMessage. Do not usetask.confirmAction.- Action confirmations — Review the target event and use task.confirmAction for supported action types.
tool_used events. Fetching them with verbose=true&start_event_id=<waiting_for_event_id> returns Event not found.
For an unrecognized waiting type, inspect the task and current endpoint documentation before responding; do not automatically treat it as an action to approve.
Answer an agent question
When the agent supplies choices, the correspondingassistant_message includes a question_expectation object:
options contains display text, not option IDs or an enforced answer schema. Render single- or multiple-choice controls according to selection_mode, while allowing a free-text answer instead. Send a non-empty answer as ordinary message.content through task.sendMessage. For multiple choices, combine the selected text into one readable message, for example:
response_method is currently fixed to send_message, never task.confirmAction. If a client encounters an unknown method, stop automatic dispatch and check the current API documentation rather than falling back to action confirmation.
In task.listMessages, question_expectation is omitted for questions with no choices; use the question’s text and waiting event type to request a free-text answer. When present, options is non-empty. Webhooks can also describe a free-text question with options: [].
The nested question_expectation.event_id exists only in webhooks and identifies the underlying question event. It is different from the webhook envelope’s event_id, which identifies the webhook notification. In task.listMessages, use the enclosing message’s id; there is no nested event_id. Neither question ID is required by task.sendMessage, and it is not a send-message idempotency key.
Confirm an action
When an action needs confirmation, the waitingstatus_detail gives its target event ID and the expected input schema:
waiting_for_event_id tells you what the user is approving. If that event is not in the current response window, fetch it explicitly:
R0ayNknItM38cc6a2DbB4W as task.confirmAction.event_id. X0SCXV59huUdjxubJrOYyx is the tool action ID and may also identify a rollback projection. Do not use it instead of waiting_for_event_id.
Connector confirmations include Gmail, Google Calendar, Outlook Mail, Outlook Calendar, Shopify delete operations, Instagram publishing, and Meta Marketing account/mode selection. The referenced tool event exposes the original structured params. Result-driven confirmations may also expose a structured result. Connector creation, update, deletion, configuration suggestions, and Agent configuration cards require the Manus UI when the API does not expose enough structured context to build the schema input safely. Expired OAuth events require the account to complete the external authorization flow before the pending operation can continue.
tool_used events normally require verbose=true. A waiting status does not force its target event into the current page. Use verbose=true with start_event_id=waiting_for_event_id when the target is outside the current response window. Profile Agent connector confirmations that exist only in a Cascade sub-lane are not exposed through the main task event timeline.
Using task.confirmAction
input format varies by waiting_for_event_type. Build it according to confirm_input_schema. Use the referenced tool params and result to explain the operation and populate schema fields when applicable. The table below provides common examples. The absence of a schema does not turn an action confirmation into an agent question.
Only submit input that matches
confirm_input_schema or is explicitly documented for the event type. Some events support { "accept": false } as a real cancellation, while others do not consume it and remain waiting. Do not invent a generic cancel input. If the input is valid but the event does not consume it, task.confirmAction returns confirmed: false and the task remains waiting.Using My Browser
You can let the agent use your local browser. When the agent needs a browser during execution, it will trigger aneedConnectMyBrowser waiting event. Use browser.onlineList to get available clients, then select one via task.confirmAction: