---
source: crewkit documentation
url: https://crewkit.io/docs/asks.md
title: "Asks"
description: "What an Ask is, who does each step from draft to Decision, how to ask people outside your organization, and what your agent sessions read."
---


An Ask puts a planning question to the people who can settle it. A person in your organization
then turns their answers into Decisions your agent sessions can read.

## Terms

[Ask](/docs/glossary#ask), [Audience](/docs/glossary#audience),
[Respondent](/docs/glossary#respondent), [addressee](/docs/glossary#addressee),
[Response](/docs/glossary#response), [Confirmed results](/docs/glossary#confirmed-results) and
[Decision](/docs/glossary#decision) are defined in the glossary. One more word belongs to this
page:

- **Receipt**: a record that one agent session applied one confirmed Decision, at one version of
  that Decision. It holds ids only, and a session keeps at most one per Decision and version. A
  receipt never changes a Decision.

## From draft to Decision

<svg role="img" aria-labelledby="ask-lifecycle-title" viewBox="0 0 360 446" width="100%" style={{ maxWidth: "440px", height: "auto", display: "block" }}>
  <title id="ask-lifecycle-title">The life of an Ask in seven steps, each with who does it and what it needs. The same steps follow as a list.</title>
  <line x1="18" y1="30" x2="18" y2="66" stroke="var(--color-fd-border)" strokeWidth="2" />
  <circle cx="18" cy="18" r="12" fill="var(--color-fd-primary)" />
  <text x="18" y="22" textAnchor="middle" fontSize="12" fontWeight="600" fill="var(--color-fd-primary-foreground)">1</text>
  <text x="42" y="23" fontSize="14" fontWeight="600" fill="var(--color-fd-foreground)">Draft</text>
  <rect x="270" y="9" width="86" height="20" rx="10" fill="none" stroke="var(--color-fd-border)" />
  <text x="313" y="23" textAnchor="middle" fontSize="11.5" fill="var(--color-fd-foreground)">Account</text>
  <text x="42" y="42" fontSize="12.5" fill="var(--color-fd-muted-foreground)">Developer or above, or a session</text>
  <line x1="18" y1="90" x2="18" y2="126" stroke="var(--color-fd-border)" strokeWidth="2" />
  <circle cx="18" cy="78" r="12" fill="var(--color-fd-primary)" />
  <text x="18" y="82" textAnchor="middle" fontSize="12" fontWeight="600" fill="var(--color-fd-primary-foreground)">2</text>
  <text x="42" y="83" fontSize="14" fontWeight="600" fill="var(--color-fd-foreground)">Publish</text>
  <rect x="270" y="69" width="86" height="20" rx="10" fill="none" stroke="var(--color-fd-border)" />
  <text x="313" y="83" textAnchor="middle" fontSize="11.5" fill="var(--color-fd-foreground)">Account</text>
  <text x="42" y="102" fontSize="12.5" fill="var(--color-fd-muted-foreground)">An owner or admin, or a manager</text>
  <line x1="18" y1="150" x2="18" y2="210" stroke="var(--color-fd-border)" strokeWidth="2" />
  <circle cx="18" cy="138" r="12" fill="var(--color-fd-primary)" />
  <text x="18" y="142" textAnchor="middle" fontSize="12" fontWeight="600" fill="var(--color-fd-primary-foreground)">3</text>
  <text x="42" y="143" fontSize="14" fontWeight="600" fill="var(--color-fd-foreground)">Answer</text>
  <text x="42" y="162" fontSize="12.5" fill="var(--color-fd-muted-foreground)">A Respondent, by the link</text>
  <rect x="270" y="149" width="86" height="20" rx="10" fill="none" stroke="var(--color-fd-border)" />
  <text x="313" y="163" textAnchor="middle" fontSize="11.5" fill="var(--color-fd-foreground)">No account</text>
  <text x="42" y="184" fontSize="12.5" fill="var(--color-fd-muted-foreground)">An addressee, signed in</text>
  <rect x="270" y="171" width="86" height="20" rx="10" fill="none" stroke="var(--color-fd-border)" />
  <text x="313" y="185" textAnchor="middle" fontSize="11.5" fill="var(--color-fd-foreground)">Passkey</text>
  <line x1="18" y1="234" x2="18" y2="288" stroke="var(--color-fd-border)" strokeWidth="2" />
  <circle cx="18" cy="222" r="12" fill="var(--color-fd-primary)" />
  <text x="18" y="226" textAnchor="middle" fontSize="12" fontWeight="600" fill="var(--color-fd-primary-foreground)">4</text>
  <text x="42" y="227" fontSize="14" fontWeight="600" fill="var(--color-fd-foreground)">Decide</text>
  <rect x="270" y="213" width="86" height="20" rx="10" fill="none" stroke="var(--color-fd-border)" />
  <text x="313" y="227" textAnchor="middle" fontSize="11.5" fill="var(--color-fd-foreground)">Passkey</text>
  <text x="42" y="246" fontSize="12.5" fill="var(--color-fd-muted-foreground)">A person; after a confirmation,</text>
  <text x="42" y="264" fontSize="12.5" fill="var(--color-fd-muted-foreground)">a session can propose</text>
  <line x1="18" y1="312" x2="18" y2="348" stroke="var(--color-fd-border)" strokeWidth="2" />
  <circle cx="18" cy="300" r="12" fill="var(--color-fd-primary)" />
  <text x="18" y="304" textAnchor="middle" fontSize="12" fontWeight="600" fill="var(--color-fd-primary-foreground)">5</text>
  <text x="42" y="305" fontSize="14" fontWeight="600" fill="var(--color-fd-foreground)">Confirm into context</text>
  <rect x="270" y="291" width="86" height="20" rx="10" fill="none" stroke="var(--color-fd-border)" />
  <text x="313" y="305" textAnchor="middle" fontSize="11.5" fill="var(--color-fd-foreground)">Passkey</text>
  <text x="42" y="324" fontSize="12.5" fill="var(--color-fd-muted-foreground)">A person</text>
  <line x1="18" y1="372" x2="18" y2="408" stroke="var(--color-fd-border)" strokeWidth="2" />
  <circle cx="18" cy="360" r="12" fill="var(--color-fd-primary)" />
  <text x="18" y="364" textAnchor="middle" fontSize="12" fontWeight="600" fill="var(--color-fd-primary-foreground)">6</text>
  <text x="42" y="365" fontSize="14" fontWeight="600" fill="var(--color-fd-foreground)">Read</text>
  <rect x="270" y="351" width="86" height="20" rx="10" fill="none" stroke="var(--color-fd-border)" />
  <text x="313" y="365" textAnchor="middle" fontSize="11.5" fill="var(--color-fd-foreground)">Account</text>
  <text x="42" y="384" fontSize="12.5" fill="var(--color-fd-muted-foreground)">A session, when it asks</text>
  <circle cx="18" cy="420" r="12" fill="var(--color-fd-primary)" />
  <text x="18" y="424" textAnchor="middle" fontSize="12" fontWeight="600" fill="var(--color-fd-primary-foreground)">7</text>
  <text x="42" y="425" fontSize="14" fontWeight="600" fill="var(--color-fd-foreground)">Receipt</text>
  <rect x="270" y="411" width="86" height="20" rx="10" fill="none" stroke="var(--color-fd-border)" />
  <text x="313" y="425" textAnchor="middle" fontSize="11.5" fill="var(--color-fd-foreground)">Account</text>
  <text x="42" y="444" fontSize="12.5" fill="var(--color-fd-muted-foreground)">A session that applied a Decision</text>
</svg>

1. **Draft.** A member with the Developer role or above writes the Ask in the Ask editor, or an
   agent session drafts it with `create_ask`. One Ask is for one Audience, in English, French or
   both.
2. **Publish.** An owner or admin publishes it, or a manager when your organization lets managers
   publish. While your organization has no verified domain, only an owner or admin can. The
   publisher's email address must be proven. An Ask with no addressees gets its Ask link here.
3. **Answer.** A Respondent answers through the link and needs no account. An addressee answers
   signed in, with a passkey.
4. **Decide.** A person with the permission to publish records a Decision on each question, with
   a passkey. After a confirmation, a session can propose a Decision, unless its conversation is
   sensitive, and a person with that permission confirms or dismisses the proposal.
5. **Confirm into context.** A person with the permission to publish confirms the Ask, with a
   passkey. This writes Confirmed results: the questions, the Decisions, the questions still open,
   and the Responses shown to the person confirming, each Respondent numbered, never named.
6. **Read.** An agent session reads the latest Confirmed results when it calls `get_ask_results`.
7. **Receipt.** A session that applied a Decision records a receipt.

Steps 4 and 5 come in either order and can repeat: a Decision recorded after the latest
confirmation reaches sessions at the next one. An addressee's one tap does both, and publishes a
draft first ([Answering from a phone](#answering-from-a-phone)).

---

## Ask someone outside your organization

An Ask for people outside your organization has no addressees: they answer through its link.

1. **Draft** the Ask for one Audience, in the Ask editor or from a session. Add no members: an Ask
   with addressees gets no link.
2. **Publish** it. Publishing creates the Ask link. It expires after 14 days, or after the 1 to
   90 days you set in **Link expires after (days)**.
3. **Share the link.** The Ask's **Sharing** tab shows the **Ask link**; send it to the Audience
   yourself. To have one person answer under a name you set, add them under **People with their
   own link** on the same tab: their answers are recorded under that name, and they cannot change
   it.
4. **Read the Responses** on the Ask's **Results** tab. Every member of your organization can read
   them. The Ask owner is told by email and at session start how many new Responses there are, never
   what they say. The **Inbox** lists Asks with Responses not yet confirmed.
5. **Decide and confirm.** On the **Results** tab, **Record** a Decision on each question, then
   **Confirm into context**.
   Sessions that read confirmed answers are summarized, analyzed and vectorized under your
   session settings ([Where it goes](/docs/asks-privacy#where-it-goes)).

Anyone who holds the Ask link can read the questions and answer, until the link has 50 Responses,
its default cap. The page shows your organization's name and, when the publisher's proven email
address is under one of your domains, that domain; without a verified domain it keeps showing it
after they leave. While they are still a member it also shows the publisher's name ([The notice
Respondents see](/docs/asks-privacy#the-notice-respondents-see)). A person with the permission to
publish can revoke the link (**Revoke a link…** in the Ask's **More actions** menu opens the
**Sharing** tab, where the revoke happens), close the Ask (**Close Ask**), or erase a Response when
its Respondent asks (**Erase** beside it on the **Results** tab).

What the Respondent sees, and how they read, change, download or erase their Response, is on
[You were sent a link](/docs/sent-a-link). What your privacy impact assessment needs is on the
[Asks privacy fact sheet](/docs/asks-privacy).

---

## Addressing an Ask to members

An Ask's addressees are set while it is a draft: in the Ask editor, **Add members** picks them
from your organization's members, and an agent or script sends their user ids as `addressee_ids`
on the Ask's create or update API call.

- **Up to 50 addressees per Ask.** Each must be an active member of the organization. An id that
  is not a member's is refused as not found, whether or not that account exists elsewhere.
- **No link is minted.** An addressed Ask is answered signed in, so publishing it creates no
  Response link, and a named link cannot be added to it.
- **A published Ask keeps its addressees.** Changing them is refused once the Ask is published.
- **Leaving the organization removes you.** When a membership ends, that person stops being an
  addressee of the organization's Asks in the same step.
- **An agent loop cannot flood anyone.** A conversation keeps at most 10 member-addressed draft
  Asks at a time.

---

## What an addressee sees

**In the dashboard.** The project's **Asks** page has an **Awaiting you** button. It lists the Asks
in that project addressed to you that are not closed or suspended, and each one opens its answer
page.

**In a crewkit session.** When a session starts in the project, its context names how many Asks
await you and how many Asks addressed to you were decided since your last session in that project,
with a link to the project's Asks. These are counts and a link only, never the questions or the
answers. An Ask awaits you while it still takes answers and a question of its current revision
has no confirmed Decision.

---

## Answering from a phone

The answer page is one column at any width: each question as a card, a set of option cards or a
text box, a **Reason** for each answer, and one confirm button at the end. Every question needs an
answer and a reason before you can confirm.

Confirming is **one tap** that does everything at once:

1. If the Ask is still a draft, it is published (the page says so above the button). Publishing
   through the tap needs the same permission as publishing any Ask.
2. Each answer becomes a confirmed Decision on its question.
3. The Decisions are confirmed into context, as Confirmed results your agent sessions can read.

Any refusal undoes all three. The tap is bound to the revision of the Ask the page showed: if the
Ask changed since, the page asks you to reload and confirm again. Tapping again with the same
answers changes nothing. An answer that differs from a Decision already settled on that question
is refused; changing a Decision is done from the Ask's own page.

---

## The passkey step-up

Answering an Ask in one tap, recording a Decision, confirming an agent's proposed Decision and
confirming Responses into context each need a **passkey sign-in in this browser within the last
5 minutes**. Anything else is refused with `step_up_required`, and the page offers **Sign in with
a passkey**, then brings you back.

The answer page asks for the passkey before it shows the form: when your sign-in is not a passkey
from the last 5 minutes, you see **Sign in with a passkey** and no questions until you have signed
in. When the 5 minutes run out while you type, Confirm is refused and the page offers the same
sign-in; your chosen answers and Reasons are kept in that browser tab and are back in the form
when you return to the same revision of the Ask. They are kept for you only, never in the link, and
are removed once they are back in the form, when your answers are recorded, when you sign out
(the passkey sign-in this page starts keeps them), and when the tab is closed. If the Ask has a
new revision by then, the form starts empty.

When Confirm is refused because a question already has a different Decision, the page links to the
Ask's own page, where a Decision is changed.

**Why a magic link is not enough.** A Decision is what your agents act on, so writing one is a
statement of human intent, and crewkit asks for proof that the person is at this browser right now:

- **A passkey, not a magic link or SSO sign-in.** A magic link proves control of a mailbox; a
  passkey proves the person holds the device. Only a passkey sign-in counts here.
- **This browser, not the CLI.** A CLI token approved through the device flow copies the
  approving browser's sign-in details. crewkit tells them apart by how the token was minted, and
  refuses any token that was not minted for the browser, so no CLI, device-flow or agent token can
  record a Decision.
- **Within 5 minutes.** A long-lived session is not fresh: the passkey sign-in must be younger than
  5 minutes.

Who may answer stays the same: an addressee may answer an Ask addressed to them in one tap whatever
their role. Recording a Decision or confirming from the Ask's own page still needs the permission
to publish Asks (an owner or admin, or a manager when your organization lets managers publish).

---

## What agents do with the Decisions

An agent never answers, decides or confirms. What reaches a session about Asks:

- **At launch, counts and a link.** How many of your Asks have new Responses, and the counts under
  [What an addressee sees](#what-an-addressee-sees). Never a question, an answer or a Decision's
  text.
- **On request, the Confirmed results.** When a session calls `get_ask_results`: before any
  confirmation, only how many Responses there are; after, the latest Confirmed results, as
  untrusted data. Responses that arrived after that confirmation show only as a count.
- **Nothing makes a session apply a Decision.** A session that applies one checks
  `get_decision_receipt` first and records a receipt with `record_decision_applied` after.
- **A proposal is not a Decision.** `record_decision` proposes one. It stays pending, and no agent
  reads it, until a person with the permission to publish confirms it in the dashboard.

The tools are listed under [Asks in the MCP server](/docs/mcp#asks).

---

## Next steps

- [Asks privacy fact sheet](/docs/asks-privacy)
- [MCP server](/docs/mcp)
