Elicit#

Gives the assistant the ability to request structured input from the user.

Elicitation supports multiple input types:

text: Free-form text input
choice: Single selection from options
multi_choice: Multiple selections from options
secret: Hidden input (API keys, passwords) with UI redaction
confirmation: Yes/No question
form: Multiple fields collected at once

Secret values are handled specially: the value is hidden from the chat display (hide=True) so it does not appear on screen, but it is passed to the LLM in-context so the agent can act on it (e.g. set it as an env var). The value is stored in the on-disk conversation log.

Instructions

### When to use elicit

Use elicit when you need structured user input that a plain text reply cannot
cleanly provide:
- **secret** — API keys, passwords, tokens. The value is hidden from the chat
  display so it does not appear over someone's shoulder; the LLM still receives
  it in-context so it can act on it (e.g. export as an env var or pass to a
  command). The conversation log on disk will contain the value.
- **choice / multi_choice** — present a fixed set of options so the user
  selects rather than types a free-form answer that you then have to parse.
- **confirmation** — ask yes/no before a destructive or irreversible action.
- **form** — collect several related fields in one interaction instead of a
  back-and-forth sequence.

Do **not** use elicit for simple open-ended questions that read naturally in
chat — a plain assistant message is clearer and less disruptive in those cases.

### Input types

- text: Free-form text input
- choice: Single selection from a list (specify options)
- multi_choice: Multiple selections from a list (specify options)
- secret: Hidden from display; LLM receives the value in-context to act on it
- confirmation: Yes/No question
- form: Multiple fields at once (specify JSON field definitions)

Examples

Ask for a secret API key

User

Set up the OpenAI integration

Assistant

I need your OpenAI API key to proceed. It will be hidden from normal chat display.elicit
{
  "type": "secret",
  "prompt": "Enter your OpenAI API key:",
  "description": "Required for the OpenAI integration. Hidden from normal chat display."
}

System

User provided secret value (not shown)

Ask user to choose an option

User

Which database should we use?

Assistant

Let me ask the user their preference.elicit
{
  "type": "choice",
  "prompt": "Which database should we use?",
  "options": [
    "PostgreSQL",
    "SQLite",
    "MySQL",
    "MongoDB"
  ]
}

System

User selected: PostgreSQL

Collect project setup information via form

User

Set up a new project

Assistant

Let me gather some details about the project.elicit
{
  "type": "form",
  "prompt": "New project setup:",
  "fields": [
    {
      "name": "name",
      "prompt": "Project name?",
      "type": "text"
    },
    {
      "name": "language",
      "prompt": "Primary language?",
      "type": "choice",
      "options": [
        "python",
        "typescript",
        "rust"
      ]
    },
    {
      "name": "tests",
      "prompt": "Include tests?",
      "type": "boolean"
    }
  ]
}

System

Form submitted: {"name": "my-project", "language": "python", "tests": true}

gptme.tools.elicit.execute_elicit(code: str | None, args: list[str] | None, kwargs: dict[str, str] | None) → Generator[Message, None, None]

Execute elicitation and return user’s response.

For secret types, the value is returned to the agent with UI redaction.

gptme.tools.elicit.parse_elicitation_spec(code: str) → ElicitationRequest | None: Parse an elicitation spec from JSON.