# Interactive Q&A

MindRoom agents can present clickable multiple-choice questions to users using Matrix reactions.
When an agent's response contains a specially formatted JSON block, MindRoom automatically renders it as a numbered list with emoji reactions that users can click to respond.

## How It Works

1. An agent includes an `interactive` code block in its response.
2. MindRoom parses the JSON, formats the options as a numbered list, and adds emoji reactions to the message.
3. The user clicks a reaction emoji or types the option number.
4. MindRoom captures the selection and feeds it back to the agent as a follow-up prompt (`"The user selected: <value>"`).

The entire flow happens within the thread where the original question was asked.

## JSON Format

Agents emit interactive questions by wrapping JSON in an `interactive` code block:

````markdown
```interactive
{
    "question": "What approach would you prefer?",
    "options": [
        {"emoji": "🚀", "label": "Fast and automated", "value": "fast"},
        {"emoji": "🔍", "label": "Careful and manual", "value": "careful"}
    ]
}
```
````

### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `question` | string | No | The question text shown above options. Defaults to `"Please choose an option:"`. |
| `options` | array | Yes | List of option objects (max 5). |
| `options[].emoji` | string | No | Emoji shown as a reaction button. Defaults to `"❓"`. |
| `options[].label` | string | No | Human-readable label for the option. Defaults to `"Option"`. |
| `options[].value` | string | No | Value passed back to the agent when selected. Defaults to the label in lowercase. |

### Rendered Output

The JSON block is replaced with a formatted message:

```
What approach would you prefer?

1. 🚀 Fast and automated
2. 🔍 Careful and manual

React with an emoji or type the number to respond.
```

The corresponding emoji reactions are added to the message as clickable buttons.

## User Response Methods

Users can respond in two ways:

- **Reaction**: Click one of the emoji reactions added to the message.
- **Text**: Send a message with a single-digit option number (e.g., `1` or `2`) in the same thread. Only digits 1–5 are recognized; multi-digit numbers like `10` are ignored.

Both methods trigger the same follow-up behavior: the agent receives the selected value and continues the conversation.

## Agent Integration

Agents don't need any special tools or configuration to use interactive questions.
Any agent can include an `interactive` code block in its response text.
You can guide agents to use this feature through their `instructions` or `role`:

```yaml
agents:
  assistant:
    display_name: Assistant
    role: A helpful assistant
    instructions:
      - >
        When the user needs to choose between options, present them using
        an interactive code block with JSON containing question and options
        (each with emoji, label, and value fields).
```

## Limitations

- Maximum of **5 options** per question. Additional options are silently truncated.
- Only **one active question per message**. If a response contains multiple interactive blocks, only the first is processed.
- Questions are tracked **in memory** and do not persist across restarts.
- Only human users can respond; reactions from other agents are ignored.
- Only the agent that created the question processes reactions to it.
