Knowledge base

Your agent needs context to answer customer questions accurately. Stellar gives you several places to put that context: reusable knowledge documents, a short general knowledge field, state-specific instructions, and actions that fetch live data.

This page focuses on knowledge documents: how to create and manage them in Studio, how to give an agent access to them, how the agent searches them during a conversation, and how to prompt the agent so it uses them well.

Choose where knowledge should live

Different types of knowledge belong in different places. The main trade-off is whether the agent should always carry the information, search for it only when relevant, or fetch it live from another system.

Use this	Best for	Avoid when
Knowledge documents	Longer reference material, shared content, policies, product details, troubleshooting guides, and FAQs the agent should search when needed	The information must shape every response or it changes in real time
General knowledge	Short, always-on facts for one agent, such as company context, support hours, or top-level constraints	The content is long, detailed, or should be reused across many agents
State instructions	Details that only apply in one dialogue step, such as billing rules in a billing support state	The same information is useful throughout the conversation
Actions	Live, customer-specific, or frequently changing data from your own systems	The answer is static and can live in written content

A full returns policy is usually a knowledge document. Support hours can live in General knowledge if they are short and apply to one agent. Billing-only refund instructions fit better in a billing state. A question like "Where is my order?" should usually call an action, because the answer depends on the customer and changes over time.

Add and manage knowledge documents

Knowledge documents hold reusable content that the agent can search when needed, without putting the full text into every response. Use them for longer or shared material: help center articles, policies, product specifications, troubleshooting guides, internal procedures, and larger FAQ sets.

The recommended way to work today is to write and manage documents directly in Studio. You stay in control of the exact wording, and every agent that uses the document picks up your changes.

Create a document

1. Navigate to Organization > Knowledge.
2. Click New document and choose Blank document.
3. Give it a clear title, a short summary, and the content itself.
4. Optionally attach one or more labels, then save.

When the agent looks for a document during a conversation, it decides which one to open based on the title and summary, so write them for that. A good summary answers "what is in here, and when should I use it?" See Write documents the agent can find for the details.

Organize with labels

Labels group related documents so you can attach them to agents in bulk. For example, you might create a "Returns policy" label and attach it to several documents that cover different return flows. Selecting a label on an agent keeps that agent in sync as you add or update documents under the label, so you rarely have to touch the agent again.

Give an agent access to knowledge documents

Creating a document does not automatically make it available to every agent. You opt each agent in and choose what it can reach.

1. Open the agent and go to its Knowledge tab.
2. Turn on Use knowledge documents.
3. Select the labels or individual documents this agent may use.

Selecting a label lets the agent access every document with that label, including ones you add later. Selecting individual documents pins the agent to exactly those documents. You can also exclude specific documents for a label.

If you use the Dialogue Builder, you can also scope knowledge per state, including pre-loading specific documents for a step such as a FAQ state. The next section explains what pre-loading does. Email agents configure the same per-state prefetch and search-scope options from their own Dialogue builder tab; see Knowledge for email agents for how retrieval and prefetching differ there.

How the agent searches and uses knowledge

When Use knowledge documents is on, the agent automatically gains two built-in abilities. You do not configure these as actions yourself; enabling the toggle is enough.

Ability	What it does
search_knowledge	Lists the documents the agent can access and returns each one's title, summary, and labels. The agent uses this to discover which document is relevant.
get_knowledge_document	Opens one specific document by its id and returns its full content. The agent uses this after it has identified the right document.

The typical flow during a conversation is:

1. The customer asks a question the agent cannot answer from its current context.
2. The agent calls search_knowledge to see which documents are available and reads their titles and summaries.
3. The agent calls get_knowledge_document on the most relevant document to read the full content.
4. The agent answers using that content.

If a state has pre-loaded documents, their titles and summaries are already in the agent's context, so the agent can skip the search step and go straight to get_knowledge_document. This is faster and more reliable, which is why pre-loading is worth setting up on states with a known topic.

Voice only

If a state sets one pre-load field (labels or documents) but leaves the other empty, voice and chat agents fill the empty field with the agent's entire accessible list for that field. The two fields are then required together, so the state can end up pre-loading less than what's listed, and sometimes nothing at all: a state that pre-loads a label pre-loads nothing if the agent's accessible documents carry no labels. Email agents never do this substitution; see when an email agent retrieves nothing.

Because discovery relies on titles and summaries, the quality of those two fields directly determines whether the agent finds the right document. Vague titles lead to missed or wrong lookups.

Prompt your agent to use knowledge

The agent also needs clear instructions on when to search, how to use what it finds, and what to do when the answer is not there.

Put the general rules in the agent's personality instructions. These apply in every state, so this is where the core knowledge behavior belongs: when to search, answering only from the knowledge, the fallback when no answer is found, language, and tone. The prompt block below is written for this field.

Do not copy the general rules into every state. Keep them in the personality instructions so they stay consistent. Instead, add knowledge instructions to the specific states where these questions are normally answered, for example a FAQ or general support state, telling the agent which topics to search for there.

Cover these points:

1. When to search. Describe the kinds of questions that should be answered from the knowledge base, so the agent recognizes them. Be concrete about your domain, for example questions about products, policies, procedures, or frequently asked questions. Tell the agent to search before answering, not to answer from memory and check afterwards.

2. How to use the knowledge. Instruct the agent to answer only with information found in its knowledge base or General knowledge field, and never to rely on outside knowledge or prior training, or to guess. Be strict about what counts as an answer: the agent should reply only when the knowledge supports the answer clearly, completely, and directly. It should not stitch together partial or loosely related passages, and if the knowledge covers the question only partly, is ambiguous, or does not match the exact question, it should treat that as "not found" rather than answer.

3. What to do when there is no answer. Tell the agent explicitly what to say and do when the knowledge base does not contain the answer, so it does not invent one. A safe fallback is to acknowledge the gap and hand over to a colleague. Tie this to a real next step, such as a transfer or handover, rather than only saying a sentence.

Also instruct the agent to:

• Answer in the active conversation language, even when the document is written in another language. Retrieving a document must not change the conversation language.
• Search silently, without a preamble such as "one moment, let me check that." It should search, then answer.
• Give a short, direct answer in its own words, and not read out document titles, ids, or long lists. This matters especially for voice.
• Search again for a follow-up question about a different subject, rather than reuse an unrelated document.
• Ask one short clarifying question before searching when a question is ambiguous.

Here is a prompt block you can adapt:

## Using your knowledge base

- When the customer asks about our products, policies, procedures, or other common questions, search your knowledge base before answering. Do not answer from memory.
- Only answer using information found in your knowledge base or General knowledge. Never use outside knowledge or prior training, and never guess.
- If the knowledge base does not contain the answer, do not make one up. Say: "I don't have the answer to that right away, let me connect you with a colleague," and hand the conversation over.
- Answer in the active conversation language, even if the document is written in another language. Do not switch languages because of document content.
- Give a short, direct answer in your own words. Do not read out document titles, ids, or long lists.

Write documents the agent can find

How you write and structure documents affects how well the agent retrieves them.

• Write descriptive titles and summaries. These are what the agent reads to decide which document to open. A summary like "How customers return an item bought online, including deadlines and refund timing" works far better than "Returns."
• Keep one topic per document. Several focused documents beat one long document. The agent can then open only what is relevant, which keeps answers accurate and responses fast.
• Use labels to scope access. Give each agent and state only the documents it needs, rather than the whole library.
• Keep dynamic data out. Prices that change often, stock levels, and anything customer-specific belong in an action, not in a document.

Use General knowledge for short context

General knowledge is a text field on the agent's Knowledge tab. Use it for either of two cases:

• Knowledge the agent should have in every conversation, such as a company description, support hours, or essential constraints. Unlike knowledge documents, this text is not searched on demand; it is always present.
• Cases where all the knowledge is compact enough that separate documents are not worth it yet. If a few short facts cover what the agent needs, keeping them here is simpler than creating documents.

Keep General knowledge concise. It is injected into the agent's context on every turn, so long policies or extensive product catalogs should move to knowledge documents instead. As your knowledge grows, or once the same text needs to be reused by multiple agents, create a knowledge document and attach it to those agents rather than copying it into each agent's General knowledge field.

# Product Information

Our main product is CloudSync, a file synchronization service for businesses.

## Support Hours

- Email support: 24/7
- Phone support: Monday-Friday, 9am-6pm EST
- Enterprise customers receive 24/7 phone support

## Common Questions

Q: Can I try CloudSync before buying?
A: Yes, we offer a 14-day free trial with full access to Business plan features.

Q: How do I cancel my subscription?
A: You can cancel anytime from your account settings under Billing > Manage Subscription.

Use state instructions for specific steps

Voice and chat navigation

The navigation described here (the Dialogue Builder) is for voice and chat agents. Email agents have the same per-state instructions field in their own Dialogue builder tab, so this guidance applies there too. Only prefetch and search-scope configuration differ between the two; see Knowledge for email agents for that part.

State instructions belong in the Dialogue Builder. Use them to control knowledge retrieval for one conversation phase, such as billing support, appointment scheduling, technical troubleshooting, or account verification.

Keep policy facts in knowledge rather than copying them into the state. Attach or pre-load the relevant documents, then tell the state when to retrieve them:

## Goal

Answer billing questions using the attached billing and refund documents.

## Steps

1. Open the document that matches the caller's question. If no matching document is pre-loaded, search the knowledge base silently.
2. Answer only when the document clearly and completely supports the answer.
3. Respond in the active conversation language. Do not change language because the document uses another language.
4. If the answer is missing or ambiguous, say you cannot give an exact answer and offer to connect the caller to a colleague.

A state is also where you point the agent at knowledge for that specific step. This is the specialized guidance mentioned in Prompt your agent to use knowledge: name the topics the agent should search for here, or tell it to rely on the documents pre-loaded for this state. Keep the general rules in the personality instructions, and use the state only for what is specific to this step.

For a state that answers general questions, spell out the goal, when to search, and exactly what to do when there is no clear answer:

## Goal

Answer the customer's general questions, but only when the answer is clearly and completely in the knowledge.

## When the customer asks a general question

- Search the knowledge base first. Do this silently: do not announce that you are looking something up before you search.
- Answer only if the knowledge supports the answer clearly, completely, and directly, using only information that exactly matches the question.
- Do not answer from prior training or assumptions, and do not combine separate passages that do not, together, give the same answer.
- Do not answer if the knowledge covers the topic only partly, is ambiguous, or does not match the exact question.
- Answer in the active conversation language. Document language must not trigger a language switch.

## When you cannot find a clear answer

- Do not give a partial answer and do not guess.
- Say exactly: "I can't give you an exact answer to that right away. I'll connect you with a colleague who can help you further."
- Then hand the conversation over.

Use actions for live data

Actions let the agent retrieve data from your systems during the conversation. Use them when the answer depends on the customer, changes often, or needs to come from an external system in real time.

For example, an agent can call an action to look up an order status, check account balance, fetch appointment availability, or confirm current pricing. This avoids copying fast-changing data into static knowledge and lets the agent retrieve only what it needs.

See Actions for details on configuring API integrations.

Sync content from a URL

In development

URL syncing is still in development and is not yet the recommended way to manage knowledge. For now, create and manage documents directly in Studio as described in Add and manage knowledge documents. The behavior below may change. Reach out to your implementation contact if you plan to use this functionality.

A synced document is still a knowledge document. The difference is how its content is maintained: it tracks a public URL, such as a help center article or product page. Stellar imports the page as markdown, checks it once a day, and shows you upstream changes before applying them. Manual edits you make in Studio stay in the document across syncs.

Open Organization > Knowledge, click New document, choose Synced from URL, paste the URL, and click Import and sync. While the page imports, you'll see progress on the document page. Once the import finishes, you can review the content, attach labels, and edit the generated summary.

The sync panel at the top of the document shows the current state:

Status	Meaning
Synced	The most recent sync succeeded
Update available	The source page changed and a preview is waiting for review
Syncing...	A sync is in progress
Sync issue	The last sync failed
Source removed	The source URL no longer returns a usable page

When an update is available, your agent keeps using the previous document content until you apply the update. Click Review update to compare your current document with the proposed update. Green highlights text added by the source page, red highlights text removed by the source page, and soft blue highlights content you added manually in Studio.

Each block of changes has a checkbox in the gutter. Use Reject all, Accept all, or Apply selection to decide which changes to keep. Apply selection is the only action that modifies your document. If you leave the review screen without applying, the update remains pending and your agent keeps using the previous version.

The History button opens a timeline of previous syncs. Each entry shows the status and timestamp, and you can expand entries to inspect changes or view error messages.

Next steps

• Test your agent in the Playground to check whether it uses knowledge correctly
• Build dialogue flows for conversation-specific instructions
• Set up actions for dynamic data retrieval
• See Knowledge for email agents for what's different when an email agent handles knowledge