> 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.md).

# AI Search

AI Search lets you search selected records in your tenant using natural-language queries. A Search Profile chooses one source Object Type, selects eligible records, and defines how their fields become searchable text. Contextual renders that text, splits it into chunks, and creates embeddings for retrieval.

A named Search Index is a query preset on a profile. It selects semantic or hybrid search, candidate count, grouping, static filters, and optional reranking. Hybrid search combines semantic matches with keyword matches.

A search returns evidence from indexed text or the corresponding source records. Your AI client or solution uses those results to answer a question. Keep source references so readers can inspect the evidence.

Contextual manages indexing and retrieval over your Native Object data, so your application can use search without maintaining a separate synchronization pipeline or integrating directly with embedding, vector search, and reranking providers.

## Get Started

* [AI Search Quickstart for Coding Agents](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/quickstart.md): prepare example records, configure a profile, and use a coding agent with the Contextual CLI to search and explain the evidence.
* [AI Search CLI Reference](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/contextual-cli.md): install the CLI, sign in, manage profiles, inspect indexing progress, and query records or matching text.
* [Query and Use Results](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/query-and-use-results.md): call the Native Object API directly from your application.

Check the returned evidence against known source records and evaluate the results before using them in your solution.

## AI Search and Agentic Search

AI Search returns a finite number of ranked matches for the query you submit. Your application can call its [Native Object API endpoints](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/query-and-use-results.md#query-through-the-native-object-api) directly to display relevant records or passages. The endpoint does not rewrite your query or generate an answer from the results.

**Agentic search** is a workflow in which a language model chooses tools to call, refines queries using earlier results, and combines evidence into an answer. AI Search can be one of those tools. The application supplies conversation context and implements the tools that the model can call.

| Goal                                                                                         | Approach                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Find troubleshooting notes for a pump that is running but barely moving water.               | Call AI Search directly and show the matching notes. This does not require an answer generation step.                                                                                                                                                                                                                                                                                                                       |
| Count work orders whose `status` field is `Open`.                                            | Use a [Query Object node](https://docs.contextual.io/documentation-and-resources/components-and-data/flows/node-reference/object/query-object.md) in a Flow, or the [Native Object API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-api.md) endpoint `POST /$query/:typeId`, and request the total matching record count. Counting AI Search matches does not give that total. |
| Investigate a pump problem using its record, troubleshooting notes, and follow-up questions. | Use an agentic workflow to look up record details, retrieve relevant text, and refine later searches using what it finds.                                                                                                                                                                                                                                                                                                   |

A semantic match indicates relevance to the indexed text. It does not establish that a record satisfies an exact field condition. For example, a template label such as “Status” makes that word searchable regardless of the record's status value. Include meaningful values and context in your [templates](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md#templates), and use structured record queries for exact field conditions and counts.

To build an agentic workflow in Contextual, use [AI Gateway](https://docs.contextual.io/documentation-and-resources/components-and-data/flows/node-reference/ai-gateway.md) and the [AI Generate node's tool calling](https://docs.contextual.io/documentation-and-resources/components-and-data/flows/node-reference/ai-gateway/ai-generate.md#tool-calling-with-ai-generate) in a Flow. Define tools whose logic calls AI Search and structured record queries as needed, then returns results to the model so it can make further tool calls or generate an answer.

For an application to use this workflow, expose the Flow as an HTTP API using an [HTTP to Flow agent](https://docs.contextual.io/documentation-and-resources/components-and-data/agents/types-of-agents/http-to-flow.md), with [HTTP In](https://docs.contextual.io/documentation-and-resources/components-and-data/flows/node-reference/network/http-in.md) to receive requests and [HTTP Response](https://docs.contextual.io/documentation-and-resources/components-and-data/flows/node-reference/network/http-response.md) to return answers. Your application calls the Flow's endpoint with the question and conversation history. The Flow passes that input to AI Generate and returns the generated answer.

## Learn and Configure

* [Search Concepts and Configuration](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md): templates, chunking, embeddings, projections, indexes, filters, and reranking.
* [Create and Manage Search Profiles](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/manage-search-profiles.md): select records, configure a profile, inspect previews, save, and check readiness.

## Query and Improve

* [Query and Use Results](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/query-and-use-results.md): query contracts, evidence, and source records.
* [Analyze and Improve Search Quality](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/improve-search-quality.md): compare results with expected matches and choose what to change.
* [Keep Search Up to Date](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/keep-search-up-to-date.md): freshness, indexing progress, repair, rebuild, and failures.


---

# 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.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.
