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

# Agentic Search

For complicated queries, like "Knicks gear from Nike or Adidas, for kids, in blue," we recommend agentic search.

Toggle to agentic mode, and an LLM plans the search: it extracts deterministic filters, may split the request into OR/AND sub-searches, runs them, and merges the results into one ranked list. Latency is higher than `default` or `keyword` (it's LLM-bound), so use it for shopping and assistant flows where result quality matters more than milliseconds.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import Channel3 from "@channel3/sdk";

  const client = new Channel3(); // reads CHANNEL3_API_KEY from env

  const results = await client.products.search({
    query: "Nike or Adidas hoodies in black or grey for men, size large",
    config: { mode: "agentic" },
  });
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from channel3_sdk import Channel3

  client = Channel3()  # reads CHANNEL3_API_KEY from env

  results = client.products.search(
      query="Nike or Adidas hoodies in black or grey for men, size large",
      config={"mode": "agentic"},
  )
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.trychannel3.com/v1/search \
    -H "x-api-key: $CHANNEL3_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "Nike or Adidas hoodies in black or grey for men, size large", "config": {"mode": "agentic"}}'
  ```
</CodeGroup>

## When to use

Prefer agentic when the request has several moving parts that should become real filters:

* **Multi-constraint shopping language** — brand, retailer, category, size, price, and attributes in one sentence
* **Alternatives and branches** — `"Nike or Adidas…"`, `"green 4-wheel or black 2-wheel…"`
* **Conversational / vibe phrasing** — descriptive language stays in the semantic query while constraints become structured filters
* **Pasted identifiers** — SKU, MPN, GTIN, UPC, or EAN that should pin and boost an exact match

If you already know exact attribute handles and values, build them yourself with [attribute filters](/guides/advanced-search) — agentic is for when the caller has natural language, not a pre-built filter tree.

## What it extracts

Natural language is turned into structured `SearchFilters` (and related ranking signals), including:

| Extracted as | Examples in the query |
| - | - |
| **Product type → category** | `"TV"` → television (taxonomy-backed, not only a keyword boost) |
| **Brand + retailer** | `"Levi's"`, `"from Best Buy"` → catalog brand / website IDs |
| **Gender + age** | `"men"`, `"boys"`, and similar combined cues |
| **Condition** | `new` / `used` / `refurbished`, including `"vintage"` / `"pre-owned"` |
| **Price min / max** | `"under $400"`, `"above $100 or below $90"` (as separate ranges when disjunctive) |
| **Colors** | Named shades → product-realistic hex matching (not string equality on `"navy"`) |
| **Category attributes** | `"waterproof"`, `"wide feet"`, `"size 10"`, `"55 inch"`, `"queen size"` against that category's schema |
| **Physical dimensions** | `"30 inches wide and 72 inches tall"` → structured L/W/H/weight filters when axes are named |
| **Exact product IDs** | SKU / MPN / GTIN / UPC / EAN → deterministic boost and pin |
| **Stock preference** | In-stock by default; widens when the user says `"even if sold out"` |

Query shapes it plans for (not just single-filter extraction):

* **Alternatives / DNF** — `"Nike or Adidas hoodies in black or grey"` → multiple sub-searches, then merge
* **Correlated constraints** — `"green 4-wheel or black 2-wheel suitcase"` keeps color tied to the other trait per branch
* **AND within one product** — `"brown and yellow sneakers"` stays one search with both colors
* **Descriptive residue** — `"cozy oversized cable knit sweater for winter"` keeps vibe language in the semantic query while filters stay clean

Attribute coverage depends on the category taxonomy. Agentic does not replace hand-built attribute filters when you already know the exact handles and values.

<Note>The filters you provide override the filters set by the agent.</Note>

## Same API surface

Request and response shapes are identical to `default` mode. Explicit `filters` combine with what the planner extracts, and pagination via `next_page_token` works as usual.

<Cards>
  <Card title="Search" icon="magnifying-glass" href="/guides/search" arrow="true">
    Text search, filters, pagination, and the other search modes.
  </Card>

  <Card title="Attribute Search" icon="sliders" href="/guides/advanced-search" arrow="true">
    Build structured attribute filters yourself for full control.
  </Card>
</Cards>


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