# Letting a Loop Search

> Name a search index in a loop, what searching lets the loop's agents do, and how the loop's visitors search

A loop can search your [Reactor search](/docs/search/overview.md) indexes, so that it answers from
your docs, your files or your records. This page is the loop's side: how a loop names an index,
what searching lets its agents do, and how the loop's visitors search. How to create an index,
and how a search is written, are in the Reactor search section.

## Let a loop search an index

Name the index in the loop's record, then publish the version:

```yaml
indexes: [docs, pricing]
```

The loop's page lists them under **What its runs may search**. A run searches only the indexes
its version names. A published version always searches an index's current content, so a new
crawl or a new file reaches the loop without a new version.

Publish refuses a name that no index on your account has. You cannot delete an index while the
newest published version of a loop uses it: the refusal names the loop.

A run in such a loop can **search** its indexes and **read** a document it found, so the loop
can answer from your docs and say which page the answer came from. Naming the indexes is enough:
each agent the loop starts may search them, whatever its role, and you do not add a capability
or a tool. The one exception is an agent that searching would bring to all three trust
properties below, such as an agent that also sends messages; it keeps its role's tools
([Permissions and trust](/docs/guide/permissions-and-trust.md)). Saving a draft refuses a loop whose
indexes no agent could search, and names the fix.

Keep the facts an index holds out of the loop's instructions. A run treats its instructions as
true, so a price written there wins over the price sheet in the index, even after the run
searched and found the newer one. Say instead which index holds what, for example *"Search
pricing for any price and quote what it finds"*. When LoopAssistant adds an index to your loop,
it takes those facts out of the instructions and says so on the card.

The run is told which indexes it has, and to search them before it answers a question they could
cover. While the loop works, a visitor reads "Searching the docs…" or "Reading the docs…", never
the name of a tool. Each search is paid from the wallet.

### What an index lets a loop do

No agent in a run may hold all three of these at once: it reads untrusted content, it touches
private data, and it acts outside the run, such as pressing a control on your page or sending a
message. Searching an index counts for the first two, unless the index says otherwise:

- A **trusted** index brings no untrusted content.
- A **site crawl** is public: the crawl sends no login, so it stores only what anybody can read.
  It brings no private data. Uploaded files and a collection's records are always private.

So an agent that searches only trusted crawls may also act. One untrusted or private index among
a loop's indexes counts for all of its searches.

Publish checks the indexes as they are, and the version keeps that reading. To let a loop act
because you marked an index trusted, publish the loop again. Marking an index **untrusted** takes
effect at once: the next run counts it, and refuses any grant that would bring an agent to all
three. If the run's agent holds all three from its start, the run's record names the index and
says to publish the loop again.

## Let your visitors search

A visitor can search what a published loop searches, through the loop's own delivery:

- **The embed's search box.** On the loop's **On your site** tab, under **What the frame shows**,
  choose the chat with a search box, or **Search only, with no chat**, before you copy the
  snippet. See [Embedding the Chat](/docs/guide/embedding-the-chat.md).
- **The React SDK's search hook**, `useSearch`, for a page you build yourself, and its
  `SearchBox`; pass `matches` to offer fewer ways to match, and one hides the choice. The SDK is
  not published yet; see [Embedding the Chat](/docs/guide/embedding-the-chat.md).
- **The run API**, `POST /api/loops/{loopId}/search`, with a key that has the `search` scope.
  See [Search](/docs/api/search.md) in the API reference.

A visitor never searches a **collection** index, even one the loop uses: a collection's records
can hold your users' data. A loop that uses only collection indexes offers visitors no search.

A visitor chooses how their text is read: the words, the exact phrase, the words allowing a
typo, or a pattern for one whole word, such as `deploy.*` or `colou?r`. The embed's search box and
the SDK's `SearchBox` show the choice as **Match**; the run API takes it as `match`. A pattern too
broad to search is refused, with what to change. [Writing a Search](/docs/search/writing-a-search.md)
shows each, and what each searcher may send. Each result shows its title, where it sits
in its document, a passage, and the page's address for a crawled page. A visitor never sees a
cost, an index's name or a score. Each search is paid from the wallet and counts against the
loop's monthly budget and the visitor's own budget; when one has no room left, the visitor reads
that search is unavailable, and no search runs.
