Manage AI references

AI references are curated documents the Envoy assistant can retrieve while answering questions. Use them for deployment-specific terminology, approved operating procedures, field definitions, and customer-facing policies that are not already in the product's built-in guidance.

References improve context; they do not grant new permissions or make unapproved operations safe.

Create a reference

An admin or superadmin can create, edit, enable, disable, or delete references. From AI references, choose New reference and enter:

• Slug — stable, unique identifier;
• Title — human-readable topic;
• Keywords — terms users are likely to ask about;
• Content — concise Markdown guidance;
• Enabled — whether retrieval can use the reference.

Example:

# Ticket migration terminology
 
- Source tenant: the account records are read from.
- Destination tenant: the account records are written to.
- Exception queue: records that require operator review.
 
Before resuming a failed write, reconcile the destination by source external ID.

Use one topic per reference. Put likely phrases and domain aliases in keywords rather than repeating them throughout the content.

What to include

Useful references contain:

• stable definitions and naming conventions;
• approved diagnostic sequences;
• data ownership and escalation boundaries;
• links or identifiers that users can access;
• cautions for irreversible actions;
• expected schemas or field semantics.

Prefer source-of-truth documentation for long procedures. Summarize only the context the assistant needs.

What not to include

Never store:

• passwords, API tokens, private keys, or connection strings;
• personal or regulated data;
• raw customer exports;
• temporary incident details;
• instructions that bypass review or access control;
• unsupported claims about external systems.

Anyone able to use the assistant may receive relevant excerpts, subject to product permissions. Treat reference content as assistant-readable operational documentation.

Maintain references

Review after a connector, schema, workflow, or policy changes. Edit a reference in place when its topic remains the same. Delete stale or superseded references so retrieval cannot surface conflicting guidance.

After an update, ask a representative question and confirm the assistant:

1. uses the correct terminology;
2. does not invent missing values;
3. cites the operational limitation;
4. asks for confirmation before a destructive operation;
5. respects the current user's permissions.

Assistant safety boundaries

The assistant's API tools use the authenticated user's access. A reference cannot bypass role checks, create hidden credentials, or make a disabled connector available. Tool results and current product state take precedence over stale reference prose.

See AI assistant and AI assistant and reference behavior.