AI

Knowledge & RAG

Retrieval-augmented generation (RAG) is how an AtomMatrix agent answers from your content — your help center, policies, product data, and documents — instead of guessing. You ingest sources into a knowledge base, AtomMatrix indexes them, and at answer time the agent retrieves the most relevant passages and grounds its reply in them, with citations. The same knowledge base works whether the customer is on chat, SMS, a phone call, or email.

How RAG works

Every grounded answer runs through four steps. You manage the first two; the platform runs the last two on each turn.

1. Ingest — add sources (URLs, files, structured records, or a live API) to a knowledge base.
2. Index — AtomMatrix splits each source into passages, embeds them as vectors, and stores them for fast semantic search. Re-indexing keeps the base fresh as content changes.
3. Retrieve — at answer time, the customer's question is embedded and matched against the index; the top passages come back with a relevance score.
4. Ground — the agent writes its reply using only those passages, and returns the sources it used so you can show citations. If nothing relevant is found, it says so or hands off rather than inventing an answer.

Knowledge sources

A knowledge base holds any mix of source types. Each is re-crawled or re-synced on a schedule so answers track your latest content.

Ingest & index

Create a base, then add sources to it. Ingestion is asynchronous: the source starts as indexing and becomes ready when its passages are searchable. Subscribe to knowledge.source.ready via webhooks to know when.

curl https://api.atommatrix.ai/v1/knowledge_bases/kb_help/sources \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://help.yourco.com/shipping",
    "refresh": "daily",
    "metadata": { "locale": "en", "topic": "shipping" }
  }'

Query the knowledge base

Agents retrieve automatically, but you can also query a base directly — useful for building your own search box, testing coverage, or pre-fetching passages. Retrieval returns ranked passages with scores and source metadata; it does not generate an answer.

curl https://api.atommatrix.ai/v1/knowledge_bases/kb_help/query \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "query": "how long does standard shipping take?", "top_k": 3 }'

Response

{
  "results": [
    {
      "source_id": "src_01HNB2...",
      "title": "Delivery windows",
      "snippet": "Standard orders ship within one business day and arrive in 3–5 business days.",
      "url": "https://help.yourco.com/shipping",
      "score": 0.86
    }
  ]
}

Grounding & citations

When an agent answers, the passages it used appear in the run's retrieval array — the same shape as the query results above. Use it to render citations, log provenance, or audit an answer. See the AI agents knowledge section for where it sits in a run.

"reply": { "role": "agent", "content": "Standard shipping takes 3–5 business days." },
"retrieval": [
  { "source_id": "src_01HNB2...", "title": "Delivery windows",
    "url": "https://help.yourco.com/shipping", "score": 0.86 }
]

RAG over SMS

An agent on an SMS number retrieves from the knowledge base on every inbound text, then answers within the constraints of the channel — concise, plain-text, and segment-aware. Long policy passages are summarized to fit, and a citation becomes a short link the customer can tap.

// Inbound SMS to an agent whose knowledge base is kb_help:
POST /v1/conversations/cnv_01HN9V.../messages
{ "role": "customer", "content": "do you ship to Canada and how long?" }

// The agent retrieves, then replies over SMS automatically:
{
  "run": {
    "retrieval": [ { "source_id": "src_ship_intl", "score": 0.83 } ],
    "reply": {
      "role": "agent",
      "content": "Yes — standard shipping to Canada takes 5–8 business days. Details: help.yourco.com/intl"
    }
  }
}

RAG on a voice call

On a call handled by an AI voice agent, retrieval runs in the same turn as speech. The caller asks a question, the agent retrieves grounded passages, and the answer is spoken back with text-to-speech — no menu tree required. Because a caller can't see a link, the agent reads the essential fact aloud and can offer to send the source by SMS or email as a follow-up.

{
  "action": "connect_agent",
  "agent_id": "agt_support_en"   // its knowledge base kb_help is retrieved on each turn
}

Retrieved passages are kept short so spoken answers stay natural, and every turn — including which sources were used — is written to the call transcript for review. If the caller's question falls outside the knowledge base, the agent says it will connect a specialist and uses transfer.

RAG in email replies

When an agent handles an inbound email, it retrieves against the whole thread, not just the last line — so a reply reflects the full context. Email has room for detail, so grounded answers can include a short quote from the source and a link to the full article, with citations preserved in the run for audit.

// Inbound email conversation; agent drafts a grounded, threaded reply:
POST /v1/conversations/cnv_01HNA1.../messages
{ "role": "customer",
  "content": "Your policy page is unclear — can I return an opened item?" }

// Reply is sent over Email, grounded in the returns policy source:
"reply": {
  "content": "Opened items can be returned within 30 days for store credit. See: help.yourco.com/returns"
},
"retrieval": [ { "source_id": "src_returns", "score": 0.88 } ]

Freshness, permissions & guardrails

• Freshness — agents always retrieve from the latest indexed version; a stale source is re-synced on its refresh cadence or on demand.
• Scoping — use metadata filters so an agent only retrieves the sources it should (by locale, product line, or audience).
• Redaction — content matched by your guardrail patterns is stripped before it reaches a reply or a log.
• Grounded-only — with retrieval required, an agent won't answer a knowledge question it can't support with a source.

See Security & governance for data residency and access controls on knowledge bases.

Common errors

See Errors & limits for the shared error object and rate limits.