# Conversational Forms

Conversational Forms replace tedious static input forms with intelligent, interactive dialogue that captures and validates structured data in real time.

Instead of presenting users with a rigid questionnaire where every question must be answered linearly, an AI Form Agent conducts a natural, fluid conversation. As details are provided, the agent progressively extracts and validates information, updating a synchronized side-panel view in real time (**progressive disclosure**).

## Why Conversational Forms?

Traditional web forms suffer from high abandonment rates, especially on mobile devices or in complex intake workflows (e.g. travel booking, medical triage, insurance claims, customer onboarding):

| Static Web Forms                                                        | Conversational Forms on AIsh.li                                                           |
| :---------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- |
| **Rigid Order**: Users must answer questions in the predefined sequence | **Natural Dialogue**: Users can provide details in any order or all at once               |
| **All-or-Nothing**: Incomplete submissions are lost                     | **Progressive Extraction**: Data is captured incrementally with each turn                 |
| **Frustrating Validation**: Ambiguous errors on submit                  | **Contextual Clarification**: The agent asks gentle follow-ups for missing fields         |
| **High Abandonment**: Long forms intimidate visitors                    | **Interactive & Engaging**: Conversational flow feels like talking to an expert concierge |

## How Progressive Disclosure Works

When interacting with a Form Agent in AIsh.li:

1. **User Speaks Naturally**: The visitor can say _"I want to book a trip from Paris to Rome tomorrow morning with Luigi"_.
2. **Entity & Schema Resolution**: The agent maps the utterance against the required fields specified in its [JSON Schema](https://json-schema.org).
3. **Live Side-Panel Updates**: The UI dynamically updates the form state drawer:
   - Extracted values (e.g. origin city, destination, traveller name) appear immediately.
   - Connected tools (such as [Google Maps](tools/maps.md)) can automatically resolve coordinates in the background.
4. **Contextual Clarification**: If any required fields remain unfilled (e.g. departure time or return date), the agent politely prompts for only the missing details.
5. **Form Completion**: Once all required schema fields are validated, the form status switches to complete and emits clean structured JSON ready for processing.

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Agent
    participant Form as Live Form Panel

    User->>Agent: "I want to travel from Paris to Rome tomorrow morning with Luigi"
    Note over Agent: Maps & Schema Resolution
    Agent->>Form: Populate resolved fields
    Note over Form: ✓ Traveller: Luigi<br/>✓ Origin: Paris<br/>✓ Destination: Rome<br/>⏳ Departure: [Pending...]
    Agent-->>User: Contextual acknowledgement + asks for departure time
```

> [!NOTE]
> **Developer vs End-User View**: In the full web app, the form state drawer is displayed alongside the conversation so builders can inspect data extraction. In the [Embeddable Chat Widget](widget.md), visitors experience a pure, seamless conversation while your backend receives the structured output via webhooks or API calls.

## Defining a Form Agent

To create a Form Agent:

1. In the [Agent Builder](/agents/new), set **Kind** to `Form`.
2. Provide a system instruction guiding the agent's tone and interview strategy.
3. Under **Output Schema**, specify a standard JSON Schema declaring the properties and `required` fields.

Here is an example excerpt from the [Transport Demo Agent](/agents/demo/transport#code):

```yaml
id: demo/transport
kind: form
instruction: >
  You are an agent who must obtain trip details from point A to B.
  Ask for missing information informally and warmly.
output:
  mediaType: application/json
  schema:
    type: object
    properties:
      name:
        type: string
        description: Traveller's full name
      origin:
        type: string
        description: Departure location and city
      destination:
        type: string
        description: Destination location and city
      origin_date_time:
        type: string
        description: Date and time of departure (ISO 8601)
    required:
      - name
      - origin
      - destination
      - origin_date_time
```

## Next Steps

- **Try It Live**: Launch the [Transport Planner in Chat](/chat/agent/demo/transport) and watch the fields populate live.
- **Inspect the Schema**: View the full declarative definition in the [Transport Agent Code Tab](/agents/demo/transport#code).
- **Backend API Integration**: Read the [Developer Forms API Guide](form-api.md) to integrate form sessions into your backend services.