> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Component gambit

> Give an AI Agent gambit native capabilities such as forms, booking, and file reading, or run one component as a flow step.

A Component gambit holds a kit of native capabilities, called components. An AI Agent gambit linked to the kit can call any of them. In Workflow Mode, the gambit runs one component as a flow step instead.

## When to use it

Use a Component gambit when the agent needs more than text: a form, a date picker, a meeting booking, a chart, or a file it reads or writes. You do not connect a toolkit or write a custom action. For a third-party action, use a tool gambit. See [Enable and use actions](https://hellotars.com/docs/guides/tools/enable-and-use-actions.md).

## Add a Component gambit

**Component** sits in the **Connected** group of the palette's **Tools** tab, beside **Knowledge Retrieval** and **CodeKit**. Drag it onto the builder.

You can also start from the AI Agent gambit. Select **Manage tools** in its **Tools & Capabilities** region, open **Add tools**, and pick **Component** under **Built-in Tools**. The new gambit is linked to the agent at once. See [AI Agent gambit](https://hellotars.com/docs/guides/building/gambits/ai-agent.md#tools-and-capabilities).

[https://dashboard.hellotars.com](https://dashboard.hellotars.com)

![A selected Component gambit linked to an AI Agent gambit's tools, with its component picker, search field, enabled count, and interaction switches](https://hellotars.com/docs/docs/guides/building/gambits/images/component-picker.png)

## Components

The components fall into three groups. The book icon on a component opens its documentation inside the editor.

| Group | What the group does | Components |
| - | - | - |
| **Interactions** | Shows a card, pauses the conversation, and resumes with the answer. | **Form**, **Button Group**, **Select Field**, **Confirmation Dialog**, **Calendar**, **Time Slots**, **Meeting Scheduler**, **File Upload**, **Verification Code** |
| **Display** | Shows a card the end user only reads. **Cards** with actions also waits for a pick. | **Cards**, **Table**, **Status List**, **Metrics**, **Timeline**, **Accordion**, **Image Gallery**, **Code Block**, **Progress Tracker**, **Chart**, **Map** |
| **Actions** | Runs on its own and returns an outcome, with nothing for the end user to answer. | **File Reader**, **File Generator**, **Data Extraction**, **Code Interpreter** |

**Web Search** is listed under **Actions** as **Coming soon** and cannot be added.

For field and upload settings, see [Form](#form) and [File Upload](#file-upload).

Two components need setup before they work. **Data Extraction** needs its fields, and **Meeting Scheduler** needs a scheduling integration. Enable the component, then select its gear icon to configure it. See [Data Extraction](#data-extraction) and [Book meetings with the Meeting Scheduler](https://hellotars.com/docs/guides/building/gambits/meeting-scheduler.md).

## Agent mode

With **Workflow Mode** off, the editor shows a **Components** section. Its badge counts the components the kit includes.

| Control | What it does |
| - | - |
| **Search components...** | Filters the list by name. |
| **Enabled** and **Disabled** | Chips that filter the list by whether the kit includes the component. |
| Component switch | Adds the component to the kit or removes it. |
| Gear icon | Opens settings for an enabled component, including required setup for **Data Extraction** and **Meeting Scheduler**. |
| Warning icon | Marks a component whose setup is incomplete. |

Link the gambit to an AI Agent gambit by dragging from its handle to the tool handle on the agent. The agent then reads each component's name and description to decide when to call it.

### Setup steps

The gear icon opens a setup dialog. For **Data Extraction** and **Meeting Scheduler**, the dialog is a series of steps that ends with **Review**. Other components open a single form. The dialog also offers these settings. **Allow free text** appears only for components that accept an answer.

| Setting | What it does |
| - | - |
| **Tool name** | The name the agent sees for this component. |
| **Tool description** | What the agent reads when deciding whether to call it. |
| **Allow free text** | Lets the end user type a reply instead of picking while the agent waits on an interaction. Off locks the composer until they pick. |

## Workflow Mode

The **Workflow Mode** switch sits at the top of the editor. With it on, the gambit runs one component as a flow step and continues on that component's outcome routes.

The **Configure Component** section holds:

| Control | What it does |
| - | - |
| **Component** | **Pick a component** opens a searchable list. Pick the one this step runs. |
| **Inputs** | The values this step sends into the component. Type @ to insert a [variable](https://hellotars.com/docs/guides/building/variables.md). Leave an optional field empty to let the component ask for it. |
| **Allow Free Text** | Lets the end user type instead of answering the card. |
| **Also in this kit** | The other components in the kit. They are not the flow step, but they are still offered to every agent linked to the kit. |

Interactions, displays, and **File Generator** can run as a flow step. The **Component** dropdown in Workflow Mode does not offer the other actions. If one was already selected, an error under the dropdown asks you to pick another component.

A **Messages** section appears once a component is picked. It holds the bubbles sent before the component.

### Outcome routes

Each outcome of the component gets its own row in the routing section, with a dropdown that picks the target gambit. An outcome with no target shows **Continue** and moves to the next step. The gambit shows one handle per outcome.

| Component type | Outcomes |
| - | - |
| **Button Group**, **Select Field**, **Calendar**, **Time Slots** | **Selected**, **Skipped**, **Free text** |
| **Form** | **Submitted**, **Skipped**, **Free text** |
| **File Upload** | **Uploaded**, **Skipped**, **Free text** |
| **Confirmation Dialog** | **Confirmed**, **Cancelled**, **Free text** |
| **Verification Code** | **Verified**, **Failed**, **Free text** |
| **Meeting Scheduler** | **Booked**, **No slots**, **Error**, **Skipped**, **Free text** |
| **Cards** | **Shown**, **Selected**, **Free text**. Cards without actions have only **Shown**. |
| Other displays | **Shown** |
| **File Generator** | **Success**, **Error** |

**Free text** appears only while **Allow free text** is on.

### Read the result

Set the gambit's **Variable** name to read its result in later steps. The outcome is stored as `{{api.gambit_variable.component_kind.outcome}}`, for example `{{api.booking.meeting_scheduler.outcome}}`. The editor lists the other result fields for the selected component under the **Component** dropdown.

## Form

In Workflow Mode, pick **Form** and fill its **Inputs**. In agent mode, describe the fields and rules in the agent's instructions so it supplies them when calling Form. In Workflow Mode, the **Docs** button opens the component's reference in the editor.

A form accepts `title`, `submitLabel`, and `submissionTitle` for the heading, submit button, and heading after submission. Its `fields` list defines each question:

| Field | What to set |
| - | - |
| `key` | A distinct answer key, such as `topic`. Use it in the result path. |
| `label` | The question the end user sees. |
| `type` | `text`, `email`, `phone`, `number`, `select`, `textarea`, `checkbox`, or `date`. |
| `required` | Require an answer. A required checkbox must be checked. |
| `placeholder` | A hint in the field before the end user answers. |
| `options` | For `select`, add a `label` and a `value` for each option. The answer stores the value. |
| `min` and `max` | Bounds for numbers or dates. Dates use `YYYY-MM-DD`. |
| `pattern` and `errorMessage` | A regular expression the answer must match and the message shown when it does not. |
| `protect` | Protect the whole answer under the active organization privacy policy. See [Form answers and protection](https://hellotars.com/docs/guides/security/personal-data-protection.md#form-answers). |

Email, phone, number, date, and select fields validate their answers before submission completes. Protection does not make the original value available everywhere: Mask mode supplies a reusable reference to supported tools, while Redact mode does not retain the original.

For a complete workflow, follow [Collect and reuse form answers](https://hellotars.com/docs/guides/building/collect-form-answers.md). The example uses a gambit with **Variable** set to `intake` and fields keyed `topic` and `details`.

Later steps can read these results:

| Reference | Value after submission |
| - | - |
| `{{api.intake.form.outcome}}` | `submitted` |
| `{{api.intake.form.answer.topic}}` | `billing` or `technical` |
| `{{api.intake.form.answer.details}}` | The submitted description. |

Use the topic reference in a condition to branch, or pass the answer references into a later tool step. See [Flow control and branching](https://hellotars.com/docs/guides/building/flow-control-and-branching.md) and [Use variables](https://hellotars.com/docs/guides/building/variables.md).

## File Upload

In Workflow Mode, pick **File Upload** and set its **Inputs**. In agent mode, tell the agent which file types and size limit to request.

| Input | What it does |
| - | - |
| `label` | The instruction above the upload area. |
| `accept` | A list of extensions or MIME types, such as `.pdf`, `image/*`, or `application/pdf`. An empty list adds no type restriction. |
| `maxSizeMb` | Maximum size per file. The default is 10 MB. Set a lower value to restrict uploads further. The web widget enforces a 10 MB cap even if a higher value is configured. |
| `multiple` | Allow several files in one answer. Off by default. |

For receipts, set `label` to **Upload your receipts**, add `.pdf` and `image/*` to `accept`, set `maxSizeMb` to `5`, and turn on `multiple` if several receipts are needed. Connect **Uploaded** to the next step, then test with an allowed file, a disallowed type, and a file above 5 MB. The end user confirms the selected files to submit them.

File Upload collects files. It does not read their contents. Link a **File Reader** component to an AI Agent gambit when the agent needs to inspect them. See [File Reader](https://hellotars.com/docs/guides/building/built-in-ai-capabilities.md#file-reader).

## Data Extraction

**Data Extraction** collects details from the end user as separate typed fields, such as an address or an order description. Each field is its own input, so the agent asks for a required field before it calls the component.

Enable **Data Extraction**, then select its gear icon to open the **Fields** step. Add up to 30 fields.

| Field | What it does |
| - | - |
| **Field name** | The key the agent fills in. |
| Type | **Text**, **Number**, **Yes / no**, **Date**, **Email**, or **Phone**. A date uses the `YYYY-MM-DD` format. |
| **Description** | Tells the agent what to collect for this field. |
| **Required** | The agent must collect this field before calling the component. |
| **Save to flow variable (optional)** | Stores the value in a flow variable, so later gambits can read it through the @ menu. |

## Other channels

Only the web widget can show a component that waits for an answer. On another channel, such as WhatsApp, that component ends with an error instead of showing its card. **Verification Code** is the exception and still sends its code.

In Workflow Mode, **Meeting Scheduler** follows its configured **Error** route. Other interactions have no **Error** route in the editor. The flow continues through the gambit's next connection. Do not read a submitted answer on that path, because no card was answered.

## Related pages

* [AI Agent gambit](https://hellotars.com/docs/guides/building/gambits/ai-agent.md)
* [Book meetings with the Meeting Scheduler](https://hellotars.com/docs/guides/building/gambits/meeting-scheduler.md)
* [Built-in AI capabilities](https://hellotars.com/docs/guides/building/built-in-ai-capabilities.md)
* [Gambit mastery](https://hellotars.com/docs/guides/building/gambits/overview.md)
* [Use variables](https://hellotars.com/docs/guides/building/variables.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.