AI Knowledge Builder: Turn Records Into KB Articles

What the AI Knowledge Builder is

The AI Knowledge Builder turns records you already have (today, past Zendesk tickets) into a searchable knowledge base your agents can retrieve from. You point it at a pool of records, choose how articles get written, hit Run, and each record either becomes a new KB article or gets merged into a similar one that already exists.

The result is a normal Macha knowledge source: articles are chunked, embedded, and reachable via search_knowledge the same way uploaded PDFs and crawled websites are. The difference is you didn't have to write them: they came out of tickets your team already resolved.

Why it exists

Most support teams already have the answers: they're sitting in solved tickets. The problem is those answers aren't retrievable. A ticket about "order stuck in transit for 5 days" solves itself once, then dies in the archive. The next customer with the same problem goes into the same queue and gets the same investigation from scratch.

The Knowledge Builder turns that historical resolution into an article. Now when an agent (or a human) searches "why is my order delayed?", the article surfaces, and the answer lands in seconds instead of hours.

Where it lives

The AI Knowledge Builder is a source type. Open Sources in the sidebar and you'll see it as one of the source-creation cards, next to "Upload documents", "Add website", and "Add webpage". Clicking it opens the builder wizard.

Once you've created one, it appears in All Sources with a purple AI Knowledge Builder tag so it's easy to pick out of a mixed list. Clicking the row opens the docs drawer showing every generated article; an Open Builder button in the drawer header takes you to the full builder page (batches, articles, config).

How the wizard is shaped

Four steps, mirroring the Studies wizard so if you know one you know the other:

1. Source: pick the adapter (today: Zendesk Tickets) and, if it needs a connector, the connector instance. Multi-instance accounts each show up separately.
2. Scope: a date range dropdown (defaults to the last 90 days for Zendesk), an optional filter query (defaults to status>=solved so you don't accidentally generate articles from unresolved tickets), and a "What the AI sees per ticket" checkbox grid so you can trim tokens by only including the fields that matter.
3. Method: how each article should be written. Two paths:
   • Prompt mode: one LLM call per record. Fast, cheap, deterministic. The default for most runs.
   • Agent mode: pick one of your Macha agents to investigate each record before writing. The agent can call its own read tools (search knowledge, fetch related orders, look up customers) to gather context, then produce a richer article. Slower and priced at the agent's model, but the resulting articles are noticeably more thorough on tickets where the resolution required investigation. Write tools on the agent are stripped for safety.
   A Skip low-value tickets toggle sits at the bottom of this step. On by default, it runs a small relevance filter before article generation and drops auto-replies, spam, and thin threads before you spend credits on them. You can edit the skip rules if your org has specific things to exclude.
4. Estimate & Run: name the builder, review the config summary (source, account, scope, ticket fields, method, agent if any, model, skip filter), see the credit estimate before launching, and hit Run.

What happens during a batch

Each batch walks the record pool one ticket at a time. For every record:

1. Already-processed check: skip if this ticket has already produced an article on this source in a prior batch.
2. Skip filter (if on): drop tickets the relevance filter marks as low-value (auto-replies, spam, thin threads).
3. Article generation: prompt mode calls the article-gen model directly; agent mode runs the agent with the ticket as context, then does a follow-up extraction pass to structure the result.
4. Embed: the article's title + body get vectorised.
5. Similarity search: look for existing articles on this source that are semantically close (cosine similarity above 0.85 by default).
6. Merge decision: if candidates exist, a small LLM decides: create a new article, update an existing one with the new insight, or attach this ticket to an existing article without rewriting its body.
7. Persist: the article lands as a Document row with editable: true, gets chunked + indexed, and shows up in the Articles tab immediately.

Progress streams live. The Batches tab shows one card per run with the status pill, human-readable start time, per-outcome counters (created, updated, attached, skipped, errored), and a Cancel button while running.

The Also asked as list

Every generated article carries a small Also asked as list: alternate phrasings of the question the article answers. It's set by the article-gen LLM using structured output and appended to the article body as a rendered block, so search_knowledge matches on both the original question and its phrasings.

When a new ticket merges into an existing article, the merge-decision LLM can propose new phrasings to add. The list stays deduplicated, and the body's block rebuilds from the union.

Editing articles by hand

Every article the builder generates is marked editable. Open any article from the Sources drawer or the builder's own Articles tab and you land in a full-screen editor built on the same rich text surface used for agent instructions.

The editor has three tabs:

• Article: the writing surface. Bold, italics, headings, lists, code blocks, block quotes; Cmd/Ctrl+S to save.
• Tickets (or your adapter's noun): the source records this article was built from. Each row shows the connector icon, the ticket subject, the account, and an external-link button that opens the ticket in Zendesk.
• Also asked as: the alternate phrasings the article answers.

Save triggers a re-embed automatically, so search stays current with your edits. The category chip and Updated at timestamp sit under the title on every tab, matching the read-view drawer so the two feel like the same object in two modes.

Navigating a big Articles list

Opening an article from the Articles tab drops you into a drawer with J/K keyboard navigation across the whole result set (same shape as the Studies record drawer). Left arrow / J moves to the previous article, right arrow / K to the next, Esc closes. An Edit button in the drawer header hands off to the full editor when you want to change something.

Re-running batches

Batches don't replace each other: each one adds to the source. Run one this week and another next week and the second batch will only process records the first didn't touch (the already-processed check keys on the record's external ID). If you want to reprocess a ticket (say the resolution changed) delete its article first, then run.

The Config tab on the builder page shows the current settings and a delete option (drops the builder, every generated article, and all batch history). A full config editor is planned; for now, delete-and-recreate is the way to change scope or method on an existing builder.

Plan availability

The AI Knowledge Builder is available on the Professional and Enterprise plans. Article generation runs on GPT-5.4 and is billed per record at that model's per-conversation rate. The skip filter and merge-decision passes run on GPT-5.4 Mini and are Macha-funded: you're not billed for them. You see the credit estimate before launching every batch.