Skip to main content

Knowledge for email agents

Email agents search and open knowledge documents the same way voice and chat agents do: turn on knowledge access, and the agent gains search_knowledge and get_knowledge_document automatically. They also have the same General knowledge field for short, always-on facts. This page covers what's specific to email: where knowledge lives on an email agent, how per-state scoping works in the email Dialogue builder tab, and what an email's processing history actually shows.

Turn on knowledge documents for an email agent​

  1. Open the email agent and go to its Knowledge tab.
  2. Turn on Use knowledge documents.
  3. Select the labels or individual documents this agent may use, and optionally exclude specific documents from a selected label.

This is the same access picker used by voice and chat agents, so labels and documents you create under Organization > Knowledge work the same way. See Add and manage knowledge documents for creating and writing them.

General knowledge​

The General knowledge field sits at the top of the same Knowledge tab and works exactly as it does for voice and chat agents: short, always-on facts that are present in every run rather than searched on demand.

It is independent of Use knowledge documents below it. The field is always available and its text is always in the agent's context, whether or not you turn documents on, so an agent can use General knowledge without using knowledge documents at all. It also stays in context during the wrap-up phase, where the agent's own Instructions are replaced by the wrap-up instructions, so wrap-up work can rely on these facts.

See Use General knowledge for short context for what belongs here rather than in a knowledge document.

Scope knowledge per state​

Open the email agent's Dialogue builder tab and edit a state to configure two knowledge settings for that step, in the same editor voice and chat agents use:

  • Cached labels and Cached documents pre-load the matching documents' titles, summaries, and labels into the agent's context as soon as it enters the state, so it can call get_knowledge_document directly instead of searching first.
  • Limit searchable knowledge narrows what the state can reach at all: pre-loading, search_knowledge, and get_knowledge_document are all restricted while the agent is in that state. Leave it off and the state can search everything in the agent's overall access scope. Turn it on and select Searchable labels or Searchable documents to restrict the state to just those; leaving both empty blocks every lookup for that state.

When an email agent retrieves nothing​

These configurations look valid in Studio and nothing in the UI warns you, but each one changes what the agent can retrieve:

  • No documents or labels are selected in the agent's access scope. With Use knowledge documents on but nothing chosen on the Knowledge tab, search_knowledge returns no documents and get_knowledge_document reports every id as not found. Voice and chat agents behave differently here: with no includes configured, they search the tenant's entire knowledge library instead of failing closed.
  • A state's Limit searchable knowledge override selects nothing the agent can reach. Turning the override on but leaving both Searchable labels and Searchable documents empty blocks every lookup while the agent is in that state, including prefetch, search, and direct document fetch, even for documents the agent could otherwise reach.
  • A state's Cached documents or Cached labels fall outside its Limit searchable knowledge override. The override applies to pre-loading too, so a cached document the override doesn't cover isn't pre-loaded. Nothing warns you that the two lists disagree: widen the override, or cache only documents it covers.
  • A state's Cached documents and Cached labels are both empty. Nothing is pre-loaded for that state, but the agent can still reach anything in its scope (or override) by calling search_knowledge once a relevant question comes up. Voice and chat agents diverge only when a state sets one prefetch field but leaves the other empty: they fill the empty field with the agent's entire accessible list for that field, and because the two fields are then required together, such a state can prefetch less than what it lists, or nothing. Email never substitutes an empty field this way, so a state prefetches exactly what it lists.

What shows up in the processing history​

Each search_knowledge and get_knowledge_document call appears as its own entry in the email's Processing History. A search entry records the titles, summaries, and labels of every document it found, the same metadata the agent used to decide what to open. A document-fetch entry records the document's id, title, and content length.

The document body itself is never stored on the email record. It's available to the model only while it's answering that email; the stored result keeps just the title and length, not the content.

This metadata is visible to everyone who can open the email, which is a wider audience than the people who can open the knowledge library itself: a support user who has access to emails but not to Organization > Knowledge still sees the titles, summaries, and labels in an email's processing history. That is deliberate, since the history is there to explain why the agent answered the way it did. Bear it in mind when a document summary carries internal detail, and note that a search entry lists every document the search matched, including ones the agent decided not to use.

Deleted and republished documents​

If a document referenced by an agent's access list, or by a state's prefetch or override, is deleted, the agent simply stops finding it: search_knowledge no longer returns it, and get_knowledge_document reports it as not found. Its id isn't removed from the configuration automatically; that cleanup runs the next time the draft is saved, and it strips any id that no longer resolves to a document. A published version keeps referencing the deleted id until you save the draft again and publish it, even though the runtime can no longer resolve it.

Watch the case where the deleted document was the only entry in a state's Limit searchable knowledge override, or the only entry in the agent's own access list. The cleanup leaves an empty selection behind, and an empty selection blocks retrieval rather than allowing everything: that state, or the whole agent, then retrieves nothing until you select something again. Nothing warns you, and the save that triggers it may have been for an unrelated change, so re-check the Knowledge tab and any state overrides after deleting documents.

Enabling knowledge affects every email​

Once Use knowledge documents is on, the search_knowledge and get_knowledge_document tool definitions, plus any state's prefetched content, are added to every request the agent makes while processing an email, not only the emails where a document actually gets read. Keep prefetch lists scoped to what a state actually needs: a larger prefetch list makes every email that reaches that state larger, whether or not the agent ends up using the content.

The wrap-up pass that runs after a reply is drafted gets both tools too, so the agent can still look something up while completing its follow-up work. Wrap-up does not run in the state the agent finished in, though: it runs in a state of its own. Nothing is pre-loaded there, and no state's Limit searchable knowledge override applies, so wrap-up can reach everything in the agent's overall access scope. If you used an override to keep a state away from certain documents, that restriction is not in force during wrap-up.

Automatic sending carries the most risk​

The real exposure from adding knowledge is a bad retrieval reaching a customer with no human check. That risk is highest when a Reply or Forward action's Delivery mode is set to Send: the drafted message, including anything pulled from a knowledge document, goes out immediately with no review. Compose and Draft delivery modes keep a human in the loop; Send does not.

There's no separate auto-send setting for knowledge itself, and the agent-level Default email action on the Settings tab doesn't control this either. That setting only chooses which button the human reviewer sees by default in the email detail view. The delivery mode on the Reply or Forward action is what decides whether a reply goes out untouched.

Turning knowledge off can erase per-state settings​

Turning off Use knowledge documents doesn't delete a state's saved Cached documents, Cached labels, or Limit searchable knowledge override by itself. But the state editor is shared with voice and chat agents, and it writes an empty knowledge configuration for any state you open and save while the toggle is off. If you turn knowledge off and then edit and save any state, even for an unrelated change, that state's prefetch and override configuration is erased. Turn knowledge back on before editing states whose knowledge settings you want to keep.

Next steps​