AKOOL’s Streaming Avatar SDK already provides the foundation for real-time video, audio, text, and microphone interaction. The next step is to make that avatar useful for your business by connecting it to trusted product documentation, policies, training materials, or support content.
This guide focuses on that knowledge layer. You will create an AKOOL Knowledge Base, connect it to a Streaming Avatar session with knowledge_id, and verify that the avatar gives grounded answers inside your own application.
Official SDK documentation shows you how to stream an avatar. This guide shows you how to make that avatar understand your business.
What You Are Building
The finished experience combines three parts: your approved knowledge sources, an AKOOL Knowledge Base that prepares those sources for conversation, and a Streaming Avatar embedded in your application. When a user asks a question, the avatar uses the connected knowledge base as context and returns the answer through synchronized speech and video.
The connection between the knowledge layer and the live session is the knowledge_id field. It is added when the Streaming Avatar session is created, before the browser joins the real-time channel.
The knowledge sources are processed inside AKOOL and represented by a knowledge_id. Your backend includes that ID when it creates the Streaming Avatar session. The browser then joins the returned session through the AKOOL SDK, allowing the avatar to answer with the approved knowledge while keeping credentials on the server.
Choose Your Build Path
If you want a working prototype quickly, copy the prompt below into an AI coding agent. If you already have an AKOOL Streaming Avatar integration—or prefer to configure the workflow yourself—continue with the Quick Start. Both paths produce the same result: a live avatar whose answers are grounded in your own content.
Option 1: Build with an AI Agent
Copy this prompt into your preferred AI coding agent and provide your AKOOL configuration when requested.
AI Agent build prompt
Build a knowledge-powered AKOOL Streaming Avatar application.
Use AKOOL’s official Streaming Avatar SDK Quick Start as the implementation reference:
https://docs.akool.com/sdk/jssdk-start
Start from the official SDK workflow instead of recreating a generic streaming demo. Add the following knowledge-base workflow:
1. Create the avatar session from a backend endpoint.
2. Read the Avatar ID, Knowledge Base ID, optional Voice ID, language, and duration from server-side configuration.
3. Include knowledge_id and mode_type: 2 in the session-creation request.
4. Return only the temporary session credentials required by the browser.
5. Use the official AKOOL JavaScript SDK for video, audio, text, microphone, and interruption controls.
6. Add an explicit End Session action.
7. Provide a small test panel for an exact-source question, a paraphrased question, and an out-of-scope question.
Keep the interface simple and use the linked AKOOL documentation as the source of truth.Option 2: Follow the Quick Start
Use this path when you want to add the knowledge layer to an existing application or understand the integration before handing it to an AI agent.
Before You Begin
You need an AKOOL account with API access, a Streaming Avatar ID, and a working Streaming Avatar application based on the official JavaScript SDK. You can create or manage a Streaming Avatar in AKOOL. Prepare the documents or public URLs the avatar should use. A Voice ID is optional.
If you have not connected to Streaming Avatar yet, complete the Streaming Avatar SDK Quick Start first. This article intentionally does not repeat its installation, channel connection, or media-handling steps.
Step 1: Prepare the Knowledge Sources
Upload supported documents or add public URLs. For a simple first test, a clean, well-structured DOCX is a practical starting point. Keep each source focused on one subject so the knowledge base can retrieve the right passage reliably.
Start with one small, authoritative source set and a narrow test scope. After the first questions return accurate answers, add more documents or URLs in controlled batches and retest.
Step 2: Create the AKOOL Knowledge Base
Complete the core setup fields: a clear name, an opening statement (prologue in the API), an instruction prompt, and the supported documents or public URLs you want AKOOL to use as sources.
Opening statement (prologue): Write the first message the avatar should say when the session starts. Keep it short, welcoming, and aligned with the knowledge base scope.
Prompt: “Answer questions using the approved knowledge sources. Be concise and helpful. If the information is not available, say so clearly and suggest the next support step.”
Wait until the sources finish processing, then copy the Knowledge Base ID. AKOOL uses this value as the knowledge_id for the live session.
Step 3: Connect the Knowledge Base to the Session
When your backend creates the Streaming Avatar session, add the Knowledge Base ID to the request. Use dialogue mode so the avatar can answer questions and continue the conversation.
Example session configuration
{
"avatar_id": "your_avatar_id",
"voice_id": "your_voice_id",
"knowledge_id": "your_knowledge_id",
"mode_type": 2
}The important detail is when this happens: knowledge_id belongs in session creation, not in the browser’s joinChat() call. Once the session is created, the browser can connect with the temporary credentials returned by AKOOL and use the standard SDK interaction flow.
Create the session from your backend, not directly in the browser, so the API key stays private. This cURL example sends the knowledge base ID when the session is created and enables dialogue mode with mode_type: 2.
Create a knowledge-powered Streaming Avatar session
curl --request POST \
--url https://openapi.akool.com/api/open/v4/liveAvatar/session/create \
--header "Content-Type: application/json" \
--header "x-api-key: <api-key>" \
--data '{
"avatar_id": "<avatar-id>",
"voice_id": "<voice-id>",
"language": "en",
"duration": 600,
"mode_type": 2,
"knowledge_id": "<knowledge-id>",
"stream_type": "agora"
}'Store the returned session credentials on the server, pass only the required join values to your client, and use them to initialize the AKOOL Streaming Avatar SDK.
Step 4: Add the Avatar to Your Application
Use the AKOOL JavaScript SDK to join the real-time channel, start chat in dialogue mode, display the remote video and audio, and send text or microphone input. This part is identical to the official SDK Quick Start; your application-specific work is deciding where the avatar appears and how users begin, interrupt, and end a conversation.
Keep the knowledge configuration on the session-creation path. This lets the same frontend support different products, regions, or audiences by selecting a different approved Knowledge Base ID on the backend.
Step 5: Verify Grounded Answers
Do not stop after the avatar connects successfully. Confirm that it is actually using the intended knowledge and responding appropriately when the answer is unavailable.
Troubleshooting Common Knowledge Base Issues
The avatar ignores the knowledge base. Confirm that the correct knowledge_id is included in the session-creation request. A knowledge base can exist in the dashboard without being attached to the active Streaming Avatar session.
Knowledge base content is not found. Check that every uploaded file or public URL has finished processing before you test. If processing is still pending or failed, the content is not yet available for retrieval.
Answers are inconsistent. Remove stale, duplicated, or conflicting source material. Keep one authoritative version of each fact, use clear headings, and retest with direct questions whose answers appear explicitly in the sources.
The session works, but dialogue does not. Verify that the session was created with mode_type: 2. Then check that the SDK is joining the same session returned by your backend and that the avatar, voice, language, and session configuration are valid. If you create a replacement session while debugging, make sure the client is not still using expired credentials from an earlier response.
Use Cases
Customer support. Let visitors ask product, setup, warranty, or policy questions through a more natural interface than a standard help-center search.
Product discovery. Guide prospects through features, plans, and recommended workflows using approved sales and product content.
Employee training. Turn onboarding guides and internal procedures into a conversational training assistant.
Education and events. Give learners or attendees a live presenter that can answer questions from course materials, speaker notes, or event resources.
Launch Checklist
☐ Knowledge sources are current, authoritative, and fully processed.
☐ The intended knowledge_id is included when the session is created.
☐ Exact, paraphrased, out-of-scope, and follow-up questions have been tested.
☐ The application provides clear Start, Interrupt, and End Session controls.
☐ The final experience has been tested with both text and microphone input.
Resources
- AKOOL Knowledge Base
- Create a Streaming Avatar Session
- Streaming Avatar SDK Quick Start
- Streaming Avatar SDK Best Practices
Frequently Asked Questions
What Is knowledge_id in AKOOL Streaming Avatar?
knowledge_id is the identifier for an AKOOL Knowledge Base. Adding it to a Streaming Avatar session tells AKOOL which processed documents and URLs the avatar should use when answering knowledge-based questions.
When Should I Add knowledge_id to the Streaming Avatar Session?
Add it during session creation on your backend, before the browser joins the session. This ensures the knowledge base is attached from the start and avoids exposing your AKOOL API key in client-side code.
What File Types Can an AKOOL Knowledge Base Use?
AKOOL documents support PDF, DOC, DOCX, TXT, MD, JSON, XML, and CSV files. You can also add public URLs. Use clean, current sources with descriptive headings, and wait for processing to finish before testing retrieval.
Can I Connect an External LLM or RAG Knowledge Base Directly?
The documented Streaming Avatar workflow uses an AKOOL Knowledge Base: add documents or URLs, obtain its knowledge_id, and include that ID when creating the session. Do not assume an arbitrary external vector database or RAG service can be attached directly unless you design and validate a separate application-level integration.
