diff --git a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx b/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx index d7da4531..86206f6f 100644 --- a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx @@ -46,6 +46,7 @@ You can control how much autonomy the Agent has when performing different types * Create plans * Execute commands * Interact with running commands (via [Full Terminal Use](/agent-platform/capabilities/full-terminal-use/)) +* Ask clarifying questions (via [Agent questions](/agent-platform/local-agents/interacting-with-agents/agent-questions/))
![Fine-tuning agent control: This permissions panel lets users customize how much autonomy the Agent has when applying code diffs, reading files, creating plans, and executing commands.](../../../../assets/agent-platform/agent-permissions-with-full-terminal-use.png)
@@ -59,6 +60,18 @@ For **Apply code diffs**, `Agent decides` currently behaves the same as `Always When all Agent permissions are set to **Always allow**, the Agent gains full autonomy (“YOLO mode”); however, any denylist rules will still override these settings. ::: +### Ask questions + +The **Ask questions** permission controls whether the Agent can pause a conversation to ask you clarifying questions before continuing. + +The available settings are: + +* **Never ask** - The Agent does not pause for clarifying questions and continues with its best judgment. +* **Ask unless auto-approve** - The Agent can ask during normal conversations, but questions are skipped while auto-approve is on. +* **Always ask** - The Agent can pause for your answer even when auto-approve is on. + +For the full user flow, see [Agent questions](/agent-platform/local-agents/interacting-with-agents/agent-questions/). + ### Command allowlist The Agent lets you define an allowlist of commands that run automatically without confirmation. It’s empty by default, but users often add read-only commands such as: diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx new file mode 100644 index 00000000..154ec71d --- /dev/null +++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx @@ -0,0 +1,56 @@ +--- +title: Agent questions +description: >- + Learn how Warp's Agent questions and AskUserQuestion tool pause conversations + for clarifying input, how answers work, and how to control the behavior. +--- + +Agent questions are clarifying prompts that let Warp's Agent pause a conversation and ask for your input before continuing. In tool-call history, API traces, or source code, this behavior may appear as `AskUserQuestion`, `ask_user_question`, or user-question handling; in Warp, it appears as an **Agent questions** card. + +Use this page to understand when the Agent asks questions, what kinds of answers are supported, and how Agent Profile permissions change the behavior. + +## Key features + +* **Multiple-choice questions** - The Agent presents options for you to choose from instead of asking an open-ended freeform question. +* **Single-select and multi-select answers** - Some questions accept one answer, while others let you select all options that apply. +* **Other answers** - When the Agent enables an **Other** option, you can type your own answer and submit it from the card. +* **Multiple questions** - A single card can contain multiple questions, with navigation controls for moving between them. +* **Skip support** - You can skip questions. The Agent receives the skipped state and continues with its best judgment. +* **Permission controls** - Agent Profiles include an **Ask questions** permission that controls whether the Agent pauses for your answer. + +## How it works + +When the Agent needs a decision from you before it can continue confidently, it can call the `ask_user_question` tool. Warp renders that tool call as an **Agent questions** card inside the conversation. + +Each question has a fixed list of options. The Agent can mark a question as single-select or multi-select, recommend one option for a single-select question, and allow an **Other** answer. Warp sends your selected options, any **Other** answer text, or the skipped status back to the Agent so it can continue with your response in mind. + +The Agent should only ask questions when the task cannot be completed safely or accurately without additional input. If you skip a question, the Agent should not ask the same question again; it should continue using the context it already has. + +## Answering Agent questions + +When an **Agent questions** card appears, choose the option or options that best match your intent. + +1. Select one or more options in the card. Multi-select questions show “select all that apply” next to the question text. +2. If **Other** appears and none of the listed options fit, click **Other**, enter your answer, and press `Enter`. +3. Click **Next** or press `Enter` to continue. For a single-select question, Warp may advance to the next question after you choose an option. +4. To skip the remaining questions, click **Skip all** or press `Ctrl+C`. + +After you answer or skip the questions, Warp summarizes the result in the conversation. You can expand the completed card to review the answers that were sent to the Agent. + +## Controlling when the Agent asks questions + +The **Ask questions** permission is part of each Agent Profile. To change it, open the Warp app and go to **Settings** > **Agents** > **Profiles** > **Permissions**, then edit the active profile. + +The available settings are: + +* **Never ask** - The Agent does not pause for clarifying questions. Warp skips the question and the Agent continues with its best judgment. +* **Ask unless auto-approve** - The Agent can pause for your answer during normal conversations, but Warp skips questions while auto-approve is on. +* **Always ask** - The Agent can pause for your answer even when auto-approve is on. + +Auto-approve is designed for unattended execution. If you want the Agent to keep running without pausing for clarifying questions, use **Ask unless auto-approve** or **Never ask**. + +## Related pages + +* [Terminal and Agent modes](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/) - Start and navigate Agent conversations in Warp. +* [Profiles & permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Configure Agent Profile permissions and autonomy settings. +* [Agent notifications](/agent-platform/capabilities/agent-notifications/) - Learn how Warp notifies you when an Agent needs your input. diff --git a/src/content/docs/agent-platform/local-agents/overview.mdx b/src/content/docs/agent-platform/local-agents/overview.mdx index 5a96c27d..b6f90fb0 100644 --- a/src/content/docs/agent-platform/local-agents/overview.mdx +++ b/src/content/docs/agent-platform/local-agents/overview.mdx @@ -25,6 +25,7 @@ Warp's client is open source under [AGPL v3](https://github.com/warpdotdev/warp/ This section covers how to interact with Warp's agents and the capabilities available during agent conversations: * [Interacting with Agents](/agent-platform/local-agents/interacting-with-agents/) - Manage AI conversations tied to sessions, attach context, continue previous threads, or start new ones. +* [Agent questions](/agent-platform/local-agents/interacting-with-agents/agent-questions/) - Answer, skip, and configure clarifying questions the Agent asks during a conversation. * [Agent Context](/agent-platform/local-agents/agent-context/) - Attach images, URLs, files, code blocks, and selections as context for your prompts. * [Model Choice](/agent-platform/inference/model-choice/) - Pick your preferred LLM from a curated set of top models, or let Warp choose the optimal one. * [Full Terminal Use](/agent-platform/capabilities/full-terminal-use/) - Let the agent drive interactive terminal apps, seeing live output and running commands. diff --git a/src/sidebar.ts b/src/sidebar.ts index 9c56c366..88694dfa 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -277,6 +277,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ items: [ { slug: 'agent-platform/local-agents/interacting-with-agents', label: 'Overview' }, 'agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes', + { slug: 'agent-platform/local-agents/interacting-with-agents/agent-questions', label: 'Agent questions' }, { slug: 'agent-platform/local-agents/interacting-with-agents/conversation-forking', label: 'Conversation forking' }, { slug: 'agent-platform/local-agents/code-diffs', label: 'Code diffs' }, 'agent-platform/local-agents/interacting-with-agents/voice',