User Prompt Tool

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.

ℹ️ 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
`schema`	object	✗	JSON Schema defining expected response structure

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

💡 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

⚠️ 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).

← Previous LSP Tool Next → API Tool