Skip to main content
The user prompt tool allows agents to ask questions and collect input from users during execution. This enables interactive workflows where the agent needs clarification, confirmation, or additional information before proceeding.

​
Configuration

toolsets:
  - type: user_prompt
The user prompt tool has no configuration options.

​
When to use it

  • When the agent needs clarification before proceeding with a destructive or irreversible action
  • Collecting credentials, tokens, or configuration values at runtime
  • Presenting choices and getting the user’s decision
  • Confirming important actions before executing them

​
Tool parameters

When the agent calls user_prompt, it passes:
ParameterTypeRequiredDescription
messagestringYesThe question or prompt text to display to the user.
schemaobjectNoJSON Schema defining the expected shape of the response.

​
Response format

The tool returns a JSON object: 
{
  "action": "accept",
  "content": {
    "field1": "user value",
    "field2": true
  }
}
ActionMeaning
acceptThe user provided a response. Check content for the value.
declineThe user declined to answer.
cancelThe user cancelled the prompt.
The agent should handle all three cases gracefully.

​
Schema examples

{
  "type": "string",
  "title": "API Key",
  "description": "Enter your API key"
}

​
Example agent

agent.yaml
agents:
  assistant:
    model: openai/gpt-4o
    description: Interactive deployment assistant
    instruction: |
      You are a deployment assistant. Before deploying:
      1. Ask the user which environment to deploy to.
      2. Ask the user to confirm before proceeding.
      If the user declines or cancels, abort and explain what would have happened.
    toolsets:
      - type: user_prompt
      - type: shell

​
UI presentation

How the prompt appears depends on the interface:
InterfaceBehavior
TUIDisplays an interactive dialog with appropriate input controls.
CLI (exec mode)Prints the prompt and reads a response from stdin.
API / MCPReturns an elicitation request to the client.
The user prompt tool requires an elicitation handler. It works in the TUI and CLI (--exec) modes. Availability in API or MCP mode depends on whether the client supports elicitation.

Shell

Execute commands after collecting user input.

Think

Reason about the user’s response before acting.

Permissions

Require confirmation for specific tool calls.

Features: TUI

Learn about the interactive terminal UI.

Build docs developers (and LLMs) love

Get started for freeTalk to us