User Prompt Tool

Table of contents

Ask the user questions and collect interactive input during agent execution.

Overview

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.

Note
When to Use
When the agent needs clarification before proceeding
Collecting credentials or configuration values
Presenting choices and getting user decisions
Confirming destructive or important actions

Configuration

agents:
  assistant:
    model: openai/gpt-4o
    description: Interactive assistant
    instruction: |
      You are a helpful assistant. When you need information
      from the user, use the user_prompt tool to ask them.
    toolsets:
      - type: user_prompt
      - type: filesystem
      - type: shell

Tool Interface

The user_prompt tool takes these parameters:

Parameter	Type	Required	Description
`message`	string	✓	The question or prompt to display.
`title`	string	✗	Optional title for the dialog window in the TUI. Defaults to `"Question"` when not provided.
`schema`	object	✗	JSON Schema defining the expected response structure (object or primitive).

Response Format

The tool returns a JSON response:

{
  "action": "accept",
  "content": {
    "field1": "user value",
    "field2": true
  }
}

Action Values

Action	Meaning
`accept`	User provided a response (check `content`)
`decline`	User declined to answer
`cancel`	User cancelled the prompt

Schema Examples

Simple String Input

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

Multiple Choice

{
  "type": "string",
  "enum": ["development", "staging", "production"],
  "title": "Environment",
  "description": "Select the target environment"
}

Boolean Confirmation

{
  "type": "boolean",
  "title": "Confirm",
  "description": "Are you sure you want to proceed?"
}

Object with Multiple Fields

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "description": "Your username"
    },
    "password": {
      "type": "string",
      "description": "Your password"
    },
    "remember": {
      "type": "boolean",
      "description": "Remember credentials"
    }
  },
  "required": ["username", "password"]
}

Number Input

{
  "type": "integer",
  "title": "Port Number",
  "description": "Enter the port number (1024-65535)",
  "minimum": 1024,
  "maximum": 65535
}

Example Usage

Here's how an agent might use the user prompt tool:

Agent: I need to deploy this application. Let me ask which environment to target.

[Calls user_prompt with message: "Which environment should I deploy to?"
 and schema with enum: ["development", "staging", "production"]]

User selects: "staging"

Agent: Great, I'll deploy to staging. Let me confirm this action.

[Calls user_prompt with message: "Deploy to staging? This will replace the current version."
 and schema with type: "boolean"]

User confirms: true

Agent: Deploying to staging...

UI Presentation

How the prompt appears depends on the interface:

TUI: Displays an interactive dialog with appropriate input controls
CLI (exec mode): Prints the prompt and reads from stdin
API/MCP: Returns an elicitation request to the client

Tip
Best Practice
Provide clear, concise messages. Include context about why you're asking and what the information will be used for. Use schemas with descriptions to guide users on expected input format.

Handling Responses

The agent should handle all possible actions:

accept: Process the content and continue
decline: Acknowledge and try an alternative approach or explain what's needed
cancel: Stop the current operation gracefully

Warning
Context Requirement
The user prompt tool requires an elicitation handler to be configured. It works in the TUI and CLI modes but may not be available in all contexts (e.g., some MCP client configurations).

What can I help you with?

User Prompt Tool