The AI overview on your search page

An Agent whose type is search answers the query a visitor typed into your site's own search. The answer appears as an AI overview: a short answer and the pages it stood on, placed above the results your search already shows. Your search stays yours; the overview sits beside it.

Both ways to show it use a key that belongs to that one Agent, made on the Agent's Put to use page:

• A publishable key (tnd_agp_…) for the snippet on your search page. It sits in your page's code, so it is not a secret: it only answers this Agent, and only on the domains you list with it.
• A secret key (tnd_agk_…) for calling the API from your own server. It is shown once. Keep it out of your pages.

A key reaches this Agent's answer and nothing else, and stops working the moment you revoke it.

The snippet

Place the box where the overview should appear, and load the script once per page:

<div data-tindre-answer data-agent="YOUR-AGENT-ID" data-key="YOUR-PUBLISHABLE-KEY" data-query-param="q"></div>
<script src="https://YOUR-WIDGET-HOST/answer.js" async></script>

Copy the snippet, with its script address and key filled in, from the Agent's On the search page channel. With nothing else set, the box reads the query from the page address — ?q=… — and asks once when the page loads. A page can hold more than one box; each one works on its own.

The box takes no space until it has something to show. It stays hidden when the search is not one worth an overview, when the Agent found nothing in its Knowledge to answer from, and when the key is revoked or not allowed on the page. In the last two cases the browser console says why, for whoever installed it.

Match your site

The box inherits your page's font and text colour. Set these custom properties on the element, or on anything around it, to adjust the rest:

Your stylesheet cannot otherwise reach inside the box, and the box cannot change your page.

The answer API

The snippet is a client of the Agent's answer endpoint. Call it from your server to render the overview your own way, with a secret key in the Authorization header:

POST https://YOUR-API-HOST/api/agents/YOUR-AGENT-ID/answer
Authorization: Bearer YOUR-SECRET-KEY

A search opens a new thread:

{ "kind": "search", "query": "Hvordan returnerer jeg en vare?", "locale": "nb" }

A message continues it, and needs the session header the search returned:

{ "kind": "message", "thread_id": "…", "message": "Gjelder det også salgsvarer?" }

A query holds up to 500 characters and a follow-up up to 4,000. locale is optional and chooses status wording only. A search may also carry page_url.

Streamed or whole

Send Accept: text/event-stream to receive the answer as it is written. Each event is a data: line of JSON:

• answer_delta carries the next piece of text.
• answer_complete carries thread_id, message_id, up to five sources (a title and a web address each), no_answer and no_answer_reason.
• error carries a reason: unavailable, too_long or failed.
• done is always last.

Without that header, the response is one JSON object with thread_id, message_id, answer, sources, no_answer and no_answer_reason.

When no_answer is true there is no overview to show, and the answer is empty. no_answer_reason says why: not_a_question (a greeting, a lone command, a fragment), navigational (the visitor wants a page, not an answer), or not_in_knowledge. Show your regular results only.

The session

The response to a search carries two headers: x-conversation-id, the new thread, and x-dialog-session, a token for this visitor. Send the token back as x-dialog-session on every follow-up in that thread. A follow-up without it, or with another visitor's, answers 404. Keep the token for as long as the visitor may continue, and send no cookies — the endpoint does not use them.

Keys and domains

A secret key needs nothing else. A publishable key is used from a browser, which sends an Origin header by itself, and it answers only when that origin is one of the key's domains; otherwise the call is refused with 403. Never put a secret key in a page: anyone can read a page's code.

Errors

A request that fails before the answer starts returns JSON with error, message and request_id:

Quote the request_id when you contact support.

What you see afterwards

Every search counts in the Agent's measurements. A search nobody followed up does not appear in the inbox; it becomes a conversation there once the visitor sends a follow-up.