> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/quickstart.md).

# AI Search Quickstart for Coding Agents

Configure a Search Profile, query tenant records with a coding agent and the Contextual CLI, and check the evidence behind an answer.

Use a coding agent and the Contextual CLI to search your tenant records and explain the matching evidence. Follow this guide to prepare a small sample dataset, configure a Search Profile, run a search, and compare the answer with a known source record.

## Before You Start

You need:

* A tenant with AI Search available, permission to configure a Search Profile, and permission to create and read records in the source Object Type. Creating the example Object Type also requires permission to create Object Types.
* Contextual CLI 0.17.0 or later.
* A coding agent that can run shell commands in an environment where `ctxl` is on `PATH` and your tenant sign-in is available.

Follow [Install and Sign In](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/contextual-cli.md#install-and-sign-in) to install the CLI and sign in to your tenant. This walkthrough uses CLI configuration ID `my-config`; replace it with your configuration ID. Complete sign-in yourself before asking your coding agent to run commands.

{% hint style="info" %}
If AI Search is unavailable in your tenant or access is denied, [Contact Contextual support](mailto:help@contextual.io) and include the tenant ID.
{% endhint %}

Choose **CLI** or **Console** for each setup task below. The example uses Object Type ID `equipment-articles` and profile ID `equipment-help`. Choose unused IDs; if you change them, update the commands and profile configuration to match.

## Prepare the Example Records

The synthetic data for this quickstart uses fictional equipment troubleshooting articles. Prepare an Object Type with the fields `title`, `category`, `symptom`, and `resolution`. Use three records with distinct topics:

| ID                    | Title                         | Category  | Symptom                                  | Resolution                                                |
| --------------------- | ----------------------------- | --------- | ---------------------------------------- | --------------------------------------------------------- |
| `pump-will-not-start` | Pump will not start           | Pumps     | The pump makes no sound when started.    | Check the power supply and reset the overload protection. |
| `pump-low-flow`       | Pump has low flow             | Pumps     | The pump runs but delivers little water. | Check the inlet strainer for blockage.                    |
| `conveyor-stops`      | Conveyor stops intermittently | Conveyors | The conveyor stops during operation.     | Inspect the emergency-stop circuit and motor protection.  |

Use `id` as the primary key. The searchable fields are strings; `symptom` is optional.

{% tabs %}
{% tab title="CLI" %}
Save this single-line Object Type definition as `equipment-articles.jsonl`:

```jsonl
{"id":"equipment-articles","type":"custom","objectType":"internal","name":"Equipment Article","pluralName":"Equipment Articles","display":"default","defaultListStyle":"table","schema":{"primaryKey":"id","type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"symptom":{"type":"string"},"resolution":{"type":"string"}},"required":["id","title","category","resolution"]}}
```

Create the Object Type in the selected tenant:

```sh
ctxl types add \
  --input-file equipment-articles.jsonl \
  --config-id my-config \
  --pretty
```

Save these three records as `equipment-records.jsonl`, one object per line:

```jsonl
{"id":"pump-will-not-start","title":"Pump will not start","category":"Pumps","symptom":"The pump makes no sound when started.","resolution":"Check the power supply and reset the overload protection."}
{"id":"pump-low-flow","title":"Pump has low flow","category":"Pumps","symptom":"The pump runs but delivers little water.","resolution":"Check the inlet strainer for blockage."}
{"id":"conveyor-stops","title":"Conveyor stops intermittently","category":"Conveyors","symptom":"The conveyor stops during operation.","resolution":"Inspect the emergency-stop circuit and motor protection."}
```

Create the records:

```sh
ctxl records add \
  --type equipment-articles \
  --input-file equipment-records.jsonl \
  --config-id my-config \
  --pretty
```

These commands create the Object Type and its three records. Keep the returned record IDs for the result check.
{% endtab %}

{% tab title="Console" %}

1. Follow [Creating an Object Type](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/creating-an-object-type.md). Use ID `equipment-articles` and display name **Equipment Article**.
2. Use this **Data Schema**, then complete creation:

```json
{
  "primaryKey": "id",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "symptom": {
      "type": "string"
    },
    "resolution": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "title",
    "category",
    "resolution"
  ]
}
```

3. Open the Object Type's records in the console and create the three records from the table above, including their `id` values.
   {% endtab %}
   {% endtabs %}

Save the records and note their IDs.

## 1. Create the Search Profile

Both paths create profile `equipment-help` over `equipment-articles`, with named Search Index `default`. Creating the profile starts indexing its source records. See [Create and Manage Search Profiles](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/manage-search-profiles.md) for profile configuration guidance.

{% tabs %}
{% tab title="CLI" %}
Save this single-line configuration as `equipment-help.jsonl`:

```jsonl
{"id":"equipment-help","name":"Equipment Help","source":{"kind":"native-object","objectType":"equipment-articles"},"template":{"language":"handlebars","body":"Title: {{title}}\nCategory: {{category}}\n{{#if symptom}}Symptom: {{symptom}}{{/if}}\nResolution: {{resolution}}"},"chunking":{"splitterId":"plain-text-window","size":1600,"overlap":10,"preserveBoundaries":true},"embedding":{"model":"voyage-4","dimensions":1024},"projections":[],"indexes":[{"id":"default","name":"Default","mode":"hybrid","topK":10,"oneResultPerDocument":true,"filters":[],"rerank":{"enabled":false,"scope":"document"}}]}
```

The configuration includes the source Object Type, body template, chunking, embedding settings, and named index. The `chunking.overlap` value `10` means 10% overlap.

Create and save the complete profile with one command:

```sh
ctxl aisearch profiles add \
  --input-file equipment-help.jsonl \
  --config-id my-config \
  --pretty
```

A successful create response confirms that the profile was saved. Check indexing progress in the next step before searching.
{% endtab %}

{% tab title="Console" %}
Open **Components → AI Search** and choose **Create Search Profile**. Set **Name** to **Equipment Help** and **ID** to `equipment-help`. Select `equipment-articles` as the **Object type**. Leave **Query predicate** empty to include all three records.

Use this **Body template**:

```handlebars
Title: {{title}}
Category: {{category}}
{{#if symptom}}Symptom: {{symptom}}{{/if}}
Resolution: {{resolution}}
```

Leave **Header template** empty. Use these initial settings:

| Setting                              | Value                            |
| ------------------------------------ | -------------------------------- |
| **Splitter**                         | `plain-text-window`              |
| **Chunk size**                       | 1,600 characters                 |
| **Overlap**                          | 10%                              |
| **Strict windows (not recommended)** | Unchecked, preserving boundaries |
| **Embedding → Model**                | `voyage-4`                       |
| **Embedding → Dimensions**           | 1,024                            |
| **Projections**                      | None                             |

Choose **Add index**. Set **ID** to `default`, **Name** to **Default**, **Mode** to **Hybrid**, and **Top K** to 10. Turn **One result per document** on and **Rerank → Enabled** off. Leave **Static filters** empty.

**Optional: inspect the template preview.** Check that the preview uses a real sample record. If it shows field placeholders, it has not demonstrated rendering against your data. Confirm that the rendered text includes the symptom and resolution, with readable labels. Check a record with optional fields missing as well. An ID for a referenced record does not provide the referenced record's descriptive text.

Use the rendered header and body to check the text that will be indexed. Chunking happens at index time. Previewing does not index records or establish search readiness.

Choose **Create profile** to save the profile and start indexing.
{% endtab %}
{% endtabs %}

See [Search Concepts and Configuration](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md) for the meaning of each setting.

## 2. Check Indexing Progress

{% tabs %}
{% tab title="CLI" %}
Read the reported build and repair progress:

```sh
ctxl aisearch profiles progress equipment-help \
  --config-id my-config \
  --pretty
```

Each call returns a snapshot of reported progress. Run it again to check for updates. Wait for the initial build to complete, and inspect any reported record failures before running the search below.
{% endtab %}

{% tab title="Console" %}
Open the profile's **Index** panel and wait for **Ready**. Inspect any reported record failures or progress warnings before running the search below. A warning about missing recent progress does not change the index status or establish that the build failed.
{% endtab %}
{% endtabs %}

Confirm the expected record is searchable with a query. Progress reports and a **Ready** status alone do not prove every record is current. See [Keep Search Up to Date](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/keep-search-up-to-date.md).

## 3. Query With Your Coding Agent

Give your coding agent this command. It must run in the same environment where you installed the CLI and signed in:

```sh
ctxl aisearch query "The pump is running but barely moving water." \
  --profile equipment-help \
  --index default \
  --config-id my-config \
  --chunks \
  --pretty
```

Then ask:

> Run this command with the Contextual CLI. Show the matching evidence and source record IDs from the actual command output. Use that evidence to explain what to inspect. If the command fails or the results do not answer the question, say so.

The command reads indexed text and search evidence; it does not change the profile or source records. The CLI returns results, and your coding agent uses those results to explain an answer.

Do not treat a plausible answer from the agent as proof that the search ran. Inspect the command and its output. Confirm that it uses your intended CLI configuration, profile, and index, then compare the source ID with the prepared **Pump has low flow** record.

## 4. Check the Result

Check that the search and answer meet these criteria:

* The coding agent runs `ctxl aisearch query` with the intended CLI configuration, profile, and index.
* The result includes **Pump has low flow** and evidence about the inlet strainer.
* The answer cites or identifies that source record.
* The recommendation follows the retrieved resolution.

Use [Query and Use Results](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/query-and-use-results.md#read-search-evidence) to interpret the evidence and source references. Save the query, actual result, and source ID as the first quality check. Continue with [Analyze and Improve Search Quality](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/improve-search-quality.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/quickstart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
