Skip to main content
Some brands already have expertise that lives in a private system: a recommendation engine that knows which rod fits a species, season, and technique, a fit model, a compatibility database. The External knowledge API lets the agent ask that system a question mid-conversation, the same way it searches your catalog or your website. The agent treats what comes back as evidence from a named source. Your catalog stays the authority for products, prices, stock, and what appears on product cards.

The request

What Anagram sends: method, headers, body, and the question format.

The response

The two shapes your endpoint may return and the field-level rules.

Status codes, limits, and failures

Timeouts, size caps, request budgets, and how each failure is handled.

Example implementation

A minimal endpoint, a test checklist, and answers that work well.

​
How it works

  1. A shopper asks something that matches the expertise you described for the source (see When the agent calls it).
  2. Anagram POSTs a single, self-contained question to your endpoint over HTTPS, with your authentication header attached.
  3. Your endpoint returns an answer (guidance plus optional citations and product references) or no answer.
  4. The agent uses the answer as guidance from a named source, resolves any product references against your synced catalog, and may run one refined catalog search before showing product cards.
  5. If your endpoint is slow, errors, or returns no answer, the agent quietly falls back to your catalog, added knowledge, and web search.

​
Setting it up

The card lives at the bottom of Brain → Knowledge. Nothing is shown until you opt in.
1

Connect

Select Connect on the External knowledge API card to reveal the form.
2

Describe the source

  • Source name (1–80 characters). How the source is described to shoppers (“Consulted Acme guide desk”).
  • When should the agent ask it? (1–1,000 characters). One paragraph telling the agent which questions this source answers. Be specific. The agent uses this text, and only this text, to decide when to call it.
3

Point at your endpoint

  • Endpoint URL. An https:// URL on a public host, at most 2,048 characters. Anagram will POST to it.
  • Auth header. The header name (default Authorization) and its secret value (at most 4,096 characters). The value is stored server-side and never shown again. Leave it blank when editing to keep the existing one, or choose Remove the saved secret to send requests without it.
4

Save and test

Save, then use Test a question with a real shopper-style question to see exactly what the agent would receive, including any failure reason. Testing works while the source is disabled and never enables it.
5

Enable

Flip the switch on when you are happy with the answers. Flip it off at any time to stop all calls; your configuration is kept.
One source per project. Every placement in the project shares it.

​
When the agent calls it

The agent consults the source before making a final recommendation when the shopper’s question matches your When should the agent ask it? description and the answer would change which products to suggest. For questions covered by that description, your experts outrank the agent’s general knowledge. It does not call the source:
  • for exact prices, stock, or availability (the catalog answers those),
  • for store policies such as shipping, returns, or warranties,
  • while it still needs a clarifying answer from the shopper,
  • more than twice in a single shopper turn.
If the guidance changes the selection criteria, the agent may run one refined catalog search before showing product cards. Product references you return are hints; the catalog decides what is actually shown.

​
Security and trust boundary

  • Endpoints must be public https:// hosts. Private, loopback, and link-local addresses are refused.
  • The authentication value is only ever attached server-side. It is not visible in Studio after saving, in the agent’s prompt, or in any transcript.
  • Responses are data, not instructions. Text in answer cannot change the agent’s rules, the tools it calls, or how it speaks to shoppers. Write answers as guidance a knowledgeable associate would give, not as commands to the agent.
  • Error bodies from your service are never shown to shoppers or to the agent.
  • First-turn suggestion responses can be cached for one hour, including answers informed by an external source. Replaying a cached answer does not call your endpoint. After expiration, the next eligible suggestion runs the agent again and can consult your source for updated advice.