Getting Started — Your First Talking AI Avatar

This guide takes you from zero to a working, talking AI avatar in about 5 minutes, once you have a Kaltura account. Copy and paste the commands.

Windows? Run these commands in WSL2, Git Bash, or PowerShell. Most steps are plain node/npm/git calls that work as-is anywhere; the one Bash-only line (export) has a PowerShell equivalent noted where it appears.

What you need before you start

1. A Kaltura account with the Agentic Avatar feature enabled. No account yet? Start a free trial →
2. Two pieces of information from your account (we'll get them in Step 1):
   • your Partner ID (a number, like 1234567)
   • your Admin Secret (a long string of letters and numbers)
3. A computer with a terminal (the Terminal app on Mac, or any command line) and Node.js 18+ installed. Check with node --version; install from nodejs.org if missing.

That's it. You do not need to install anything from Kaltura.

Step 1: Get your credentials (~1 minute)

Your Partner ID and Admin Secret are your keys to the system.

1. Log in to the Kaltura Rich Media CMS at kmc.kaltura.com (or your account's custom URL if your organization has one).
2. Go to Settings → Integration Settings.
3. Copy your Partner ID (shown at the top) and your Administrator Secret.

Keep your Admin Secret private. It's like a password. Never paste it into a public chat, a screenshot, or a file you might share.

Step 2: Set up the project (~1 minute)

Clone the repository and install the quickstart's dependencies:

git clone https://github.com/kaltura/intelligent-agents-sdk.git
cd intelligent-agents-sdk/quickstart
npm install

Then set your credentials for this shell session:

export AGENTIC_PARTNER_ID=1234567
export AGENTIC_ADMIN_SECRET=your_admin_secret_here

Windows PowerShell? Use $env:AGENTIC_PARTNER_ID="1234567" instead of export.

Prefer a file over exporting every time? Create a .env file in the repo root (one directory up from quickstart/) with AGENTIC_PARTNER_ID=... and AGENTIC_ADMIN_SECRET=... on their own lines. create-agent.mjs reads it automatically if present. It's already covered by .gitignore, so it never gets committed.

Using the SDK in your own project? Run npm install "github:kaltura/intelligent-agents-sdk#semver:^1". It installs the latest 1.x from GitHub, because the package is not on the npm registry. Then import from @kaltura/intelligent-agents/management (server) and @kaltura/intelligent-agents/experience (browser).

Step 3: Create your own agent from scratch (1–3 minutes)

This one command builds a brand-new agent (intellect, face, voice, and all) from a plain-English description:

node create-agent.mjs "A friendly yoga studio receptionist who helps people book classes and answers questions about memberships"

It prints three status lines ([1/3] to [3/3]) and a heads-up before the slow provisioning step. At the end it sends a smoke-test message and prints the reply, plus the new IDs (configId, agentId, avatarId, widgetId) you need to embed or extend the agent. The agent is created with a silent opening (openingPhrase: SILENT_OPENING), so the browser decides how the conversation starts (see below).

Building an agent by hand instead of via the one-line brief? See Agent Components in API-REFERENCE.md.

Step 4: Talk to your agent again (~30 seconds)

create-agent.mjs already sent one smoke-test message for you. To send more, use the SDK's headless converseOnce() directly. Save this as a small script (or adapt quickstart/create-agent.mjs):

import { Management } from '@kaltura/intelligent-agents/management';

const kaltura = new Management({
  partnerId: process.env.AGENTIC_PARTNER_ID,
  adminSecret: process.env.AGENTIC_ADMIN_SECRET,
});

const reply = await kaltura.converseOnce('<configId from Step 3>', 'Hello! What can you help me with?');
console.log(reply.text);

Partner outside the US? Add region: 'frp2' (EU) to the Management config. See Regions and base URLs.

converseOnce() mints its own conversation token from the configId. The admin secret never leaves your process. See Conversation & Analytics in API-REFERENCE.md for threaded conversations, streaming, and the full Management API surface.

In the browser, let the agent speak first. Pass kickoff to the session and the SDK sends that text as the first turn, once, as soon as the server accepts input. With the silent opening the quickstart set, the greeting is the agent's own reply. Scripted or silent opening: Start the Conversation § Choose an opening. Attach listeners first: README.md § Experience.

const session = new KalturaAvatarSession({ ...runtimeConfig, kickoff: 'Greet the user and briefly say how you can help.' });
await session.connect();

Talking on behalf of a real, known user? Mint the conversation token yourself with userId instead of letting converseOnce() auto-mint an anonymous one. This binds the KS (Kaltura Session) to that user. The user gets their own threads, and {{ sys__user_id }} resolves in prompts:

const conv = await kaltura.sessions.createConversationToken({
  configId: '<configId from Step 3>',
  agentId: '<agentId from Step 3>',
  userId: 'learner-123',   // any stable id you use to identify this person
});
const reply = await kaltura.converseOnce('<configId from Step 3>', 'Hello again!', {}, conv);

userId is required on admin tokens and optional on conversation and agent tokens, but pass one for real users. What each token can reach: Security & Compliance § Session type.

agentId labels the thread, so lifecycle rules scoped to object.agent_id match it. Without it the thread gets agent_id: "default". createAgentToken is the alternative when you start from an agentId: Conversation token or agent token?.

What's next?

You now know how to create an agent and talk to it. Here's where to go for more:

Common questions

Do I need to keep the terminal open? No. create-agent.mjs runs once and exits.

Will this cost money / use my quota? Conversations and avatar sessions use your Kaltura plan's quota. Creating agents/avatars is cheap, but clean up test ones you don't need. See agents.delete() / avatars.delete() under Management Operations in API-REFERENCE.md.

How do I see everything I created? Use the Management API's list calls: kaltura.agents.list(admin.ks) and kaltura.avatars.list(admin.ks). See Management Operations in API-REFERENCE.md.

How do I label the agents I create so I can find mine later? Tag the agent (not the avatar) via adminTags on agents.create(), then filter with agents.list(admin.ks, { filter: { adminTagsIn: ['<tag>'] } }). Details under Create an Agent.

Can I use my own face or voice? Yes, both. See Catalog & Assets (visual) and → Custom Voice.