The response

Respond with HTTP 200 and a JSON body in one of two shapes. Anything else is treated as a failure (see Status codes, limits, and failures).

Shape 1: an answer

{
  "version": 1,
  "status": "answer",
  "answer": "For river smallmouth in October, a 6'10\"–7' medium-light, fast-action spinning rod gives the sensitivity finesse jigs need. Pair it with 8–10 lb fluorocarbon.",
  "citations": [
    {"title": "Fall smallmouth guide", "url": "https://example.com/guides/fall-smallmouth"}
  ],
  "products": [
    {"kind": "shopify_product", "value": "gid://shopify/Product/1234567890"},
    {"kind": "shopify_variant", "value": "gid://shopify/ProductVariant/9876543210"},
    {"kind": "handle", "value": "river-finesse-spinning-rod"}
  ]
}

Shape 2: no answer

Use this when the question is outside what your system knows. It is a normal, expected outcome, not an error.

{"version": 1, "status": "no_answer"}

The agent carries on with your catalog, added knowledge, and web search. The shopper is not told the source declined.

Field rules

Field	Required	Rules
`version`	Yes	Must be the number `1`. Other numbers fail with `unsupported_version`; missing or non-numeric values fail with `invalid_response`.
`status`	Yes	`"answer"` or `"no_answer"`.
`answer`	For `answer`	Non-empty after trimming, at most 10,000 characters. Plain text or light Markdown (paragraphs, lists, bold). No HTML.
`citations`	No	Array of at most 8. Each item needs `title` (1–200 characters) and `url` (an `https://` URL, at most 2,048 characters).
`products`	No	Array of at most 8 product references. See below.

Validation is strict on the fields above and lenient on everything else. Unknown keys are dropped before the agent sees the response, so you cannot pass extra fields through to the model. A body that fails validation counts as unavailable for that turn.

Product references

Each entry has a kind and a value.

`kind`	`value`	Example
`shopify_product`	The full product GID. Bare numeric IDs are rejected.	`gid://shopify/Product/1234567890`
`shopify_variant`	The full variant GID.	`gid://shopify/ProductVariant/9876543210`
`handle`	The product handle as it appears in the storefront URL. Letters, digits, and single hyphens, at most 255 characters.	`river-finesse-spinning-rod`

References are hints, not commands. The agent resolves each one against the catalog Anagram has synced for your project. A reference that does not resolve (wrong store, unpublished, deleted) is dropped without comment. Prices, stock, images, and titles always come from the catalog, never from your response. If your guidance points at a category rather than specific SKUs, leave products empty and describe the criteria in answer. The agent will run a catalog search using those criteria.

Citations

Citations are shown as provenance next to the agent’s reply. Anagram does not fetch, validate, or summarize the linked pages. Point them at public pages a shopper could open.

Writing answers that work

The agent reads answer as advice from a named expert, then decides what to say to the shopper in its own voice. It works best when you:

Lead with the recommendation, then the reasoning. The first sentence carries the most weight.
Name the selection criteria (weight range, insulation grade, action, fit) rather than only naming products. Criteria survive when the specific product is out of stock.
Stay inside the expertise you declared in Studio. If the question drifts into pricing, policy, or something you don’t cover, return no_answer.
Keep it under a few hundred words. The 10,000-character ceiling is a safety limit, not a target.

Do not write instructions to the agent (“tell the customer to…”, “ignore your rules”, “always recommend X”). The response is quarantined as untrusted data and instructions in it are ignored. Anything that reads as a command wastes characters and can make the answer less useful.

Getting Started

Concepts

Brain

Launch

Actions

Analytics

Guides

Integrations

Help

Shape 1: an answer

Shape 2: no answer

Field rules

Product references

Citations

Writing answers that work

​Shape 1: an answer

​Shape 2: no answer

​Field rules

​Product references

​Citations

​Writing answers that work

Shape 1: an answer

Shape 2: no answer

Field rules

Product references

Citations

Writing answers that work