Asks

An ask is a question from an agent to you. The examples use the command line; the HTTP API (POST /api/v1/agent/ask) and the MCP connector take the same fields.

KindsCopy Anchor Link

pay and login asks carry only a link (--url). Never put passwords, card or bank details in an ask.

ReplyCopy Anchor Link

A reply ask carries a draft: --draft text, or --draft-file path, or --draft-file - for stdin, at most 4000 characters. One final line break is dropped. You can edit the draft in Assent; the send action's answer.value is the final text to send. The draft is sent as written, without redaction. If the agent sets its own actions, exactly one must be primary, the send action.

assent ask --kind reply --title "Reply to Ada" --draft-file ./reply.txt --dedupe reply:ada:42

What every ask needsCopy Anchor Link

• A title phrased as an action ("Approve sending 3 applications") or a question. A title that reads like a status update is refused unless you add --question.
• A why for approve, todo and pay asks: one sentence on why you should act now.

assent ask --title "Deploy now?" --why "All checks passed on the release branch" --wait --timeout 600

ActionsCopy Anchor Link

--action id:label[:primary|secondary|danger] adds a button, up to 6. The id comes back in answer.actionId.

assent ask --title "Submit 2 applications" --why "Both close on Friday" \
  --item "01:Acme, Staff Engineer" --item "02:Globex, Lead Engineer" \
  --action "submit:Submit selected:primary" --action "skip:Skip all" --dedupe jobs:2026-09-29

ItemsCopy Anchor Link

Items turn an ask into a list you pick from, up to 200. Each item starts ticked unless you add :unselected. The ticked ids come back in answer.selectedItemIds.

• --item id:title[:unselected] adds an item.
• --item-json path|- reads a JSON array of items instead, for per-item fields, subtitles and field tones.
• --recommend item-id marks recommended items. When any item is recommended, only the recommended ones start ticked.
• --reason item-id:text adds a line on why.
• --badge item-id:label[:tone] adds a badge, at most 4 per item. Tones are neutral, ok, warn, danger and note.
• --link item-id:label:url adds an http or https link, at most 4 per item.
• --attach item-id:path uploads a file and attaches it to the item, at most 4 per item. Attachments work once you turn them on for the agent.

FieldsCopy Anchor Link

--field key:label[:type]:value shows a labelled value, up to 12. Types are text, money (GBP 42.00), date, datetime, number and score (8/10).

GroupsCopy Anchor Link

--group key:title puts separate asks from the same agent with the same key into one decision card. The key cannot contain a colon.

• --conflict-on field-key (up to 4) flags members that share that field's day or value, for example two bookings on one evening.
• --total-of field-key totals the open members of a money field, per currency.
• --decline-action action-id is what Keep one answers the other members with.

Times, reminders and repeatsCopy Anchor Link

• --due when sets a due time and --remind when a reminder. See Notifications for when pushes arrive.
• --dedupe key returns the live ask with that key instead of creating another one.
• An approve or todo ask whose title closely matches an open one from the same agent is merged into it, unless you pass --dedupe, --group or --allow-duplicate.
• --idempotency-key uuid makes a retry return the ask the first request created.
• --question, --answer-type yes_no|choice|text|number|done, --effort minutes (1 to 1440) and --series key add context. choice needs at least two actions or items.
• --project project-uuid [--track name] files the ask into a project you linked the agent to.
• --rule-action name and --target t name what an approval is about, so you can answer Always or Never. See Rules.

Getting the answerCopy Anchor Link

An answer looks like this:

{ "actionId": "submit", "selectedItemIds": ["02"], "value": "only for code and reply asks" }

There are three ways to get it.

• Wait. --wait blocks until you answer, checking every --interval seconds (default 15) for up to --timeout seconds (default 3600). It exits 0 with the answered ask, or when the ask is resolved as done while it waits. It exits 6 if the wait timed out, and 3 if the ask expired, was withdrawn or was otherwise closed without an answer. An ask that a standing rule answers comes back at once.
• Poll later. assent answers lists answered asks that are not picked up yet, oldest first. assent task get <task-uuid> reads one ask.
• Run now. With the Mac helper, answering restarts the agent with the answer in its environment.

Picked upCopy Anchor Link

Once the agent has acted on an answer, it marks it picked up so it is never delivered again:

assent picked-up "$TASK"

--wait does this for you unless you pass --no-pickup. If the Mac helper already claimed the answer to resume the agent, --wait exits 3 and the output says "resumedBy": "helper".

Closing an ask yourselfCopy Anchor Link

assent task resolve <task-uuid> closes an ask the agent created once the work is done, and --withdraw withdraws it when it is no longer needed. Its reminders stop and its notification clears. Asks other than to-dos expire if nobody answers them in time; the ask's answerExpiresAt says when.

Reporting each itemCopy Anchor Link

For an ask with items, the agent can report each item as it finishes, and check whether an item is still wanted before it starts:

assent task item-result "$TASK" 02 done --url https://example.com/application/02
assent task item-status "$TASK" 02