# 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 →](https://subscription.kaltura.com/purchase-manager/purchase-manager/avatar-studio-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](https://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](https://kmc.kaltura.com) (or your account's custom URL if your organization has one). 2. Go to [**Settings → Integration Settings**](https://kmc.kaltura.com/index.php/kmcng/settings/integrationSettings). 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:
```bash 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: ```bash 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: ```bash 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](https://kaltura.github.io/intelligent-agents-sdk/reference/api/build/index.md) 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`): ```js 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('', '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](https://kaltura.github.io/intelligent-agents-sdk/reference/api/authentication/index.md#regions-and-base-urls). `converseOnce()` mints its own conversation token from the `configId`. The admin secret never leaves your process. See [Conversation & Analytics](https://kaltura.github.io/intelligent-agents-sdk/reference/api/operate/index.md) 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](https://kaltura.github.io/intelligent-agents-sdk/guides/start-the-conversation/index.md#choose-an-opening). Attach listeners first: [README.md § Experience](https://github.com/kaltura/intelligent-agents-sdk/blob/main/README.md#experience). ```js 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](https://kaltura.github.io/intelligent-agents-sdk/reference/api/authentication/index.md#authentication) (Kaltura Session) to that user. The user gets their own threads, and `{{ sys__user_id }}` resolves in prompts: ```js const conv = await kaltura.sessions.createConversationToken({ configId: '', agentId: '', userId: 'learner-123', // any stable id you use to identify this person }); const reply = await kaltura.converseOnce('', '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](https://kaltura.github.io/intelligent-agents-sdk/reference/security/index.md#session-type). `agentId` labels the thread, so [lifecycle rules](https://kaltura.github.io/intelligent-agents-sdk/reference/lifecycle/index.md#scoping-a-rule-to-one-agent) 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?](https://kaltura.github.io/intelligent-agents-sdk/reference/api/authentication/index.md#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: | If you want to… | Read this | |-----------------|-----------| | See every kind of app you can build (personalized greeters, memory agents, quizzes, video avatars, voice cloning…) | [Use-Case Catalog](https://kaltura.github.io/intelligent-agents-sdk/reference/use-cases/index.md) | | Look up the exact API call for something | [Backend API Reference](https://kaltura.github.io/intelligent-agents-sdk/reference/api-reference/index.md#contents) | | Put a talking video avatar on a web page | [Use-Case Catalog](https://kaltura.github.io/intelligent-agents-sdk/reference/use-cases/index.md) → UC-12 | | Make the avatar greet the user first, interruptibly, as fast as possible | [Start the Conversation](https://kaltura.github.io/intelligent-agents-sdk/guides/start-the-conversation/index.md) | | Use your **own voice** for the avatar | [Catalog & Assets](https://kaltura.github.io/intelligent-agents-sdk/reference/api/design/index.md#upload-a-custom-voice-clone) | | Use your **own face/portrait** for the avatar | [Catalog & Assets](https://kaltura.github.io/intelligent-agents-sdk/reference/api/design/index.md#upload-a-custom-visual-portrait--animated-avatar) | | Build a real app with the JavaScript SDK | [README.md](https://github.com/kaltura/intelligent-agents-sdk/blob/main/README.md#quick-start) | | Let Claude Code build it with you | [Using Claude Code or another coding agent](https://github.com/kaltura/intelligent-agents-sdk/blob/main/README.md#using-claude-code-or-another-coding-agent) | | Make the avatar drive your UI (slides, widgets, navigation) | [Client-Side Commands](https://kaltura.github.io/intelligent-agents-sdk/guides/client-commands/index.md) | | Pause the avatar for a video/interactive element, then resume | [Pause for Video/Interactive Content, Then Resume](https://kaltura.github.io/intelligent-agents-sdk/guides/pause-resume/index.md) | | Auto-summarize every conversation and email a human when it's ready | [Lifecycle Recipes](https://kaltura.github.io/intelligent-agents-sdk/guides/lifecycle-recipes/index.md) | | Put structured widgets on screen (quizzes, carousels, code blocks) | [GenUI Reference](https://kaltura.github.io/intelligent-agents-sdk/reference/genui-reference/index.md) | | Understand how the whole system works under the hood | [Platform Overview](https://kaltura.github.io/intelligent-agents-sdk/explanation/architecture/index.md) | | Look up a term, or find which ID (`configId`, `agentId`, `avatarId`, `widgetId`) to use where | [Glossary](https://kaltura.github.io/intelligent-agents-sdk/reference/glossary/index.md) | | Make the agent speak and listen in one language | [Languages](https://kaltura.github.io/intelligent-agents-sdk/guides/languages/index.md) | | Run every demo in `examples/` | [Live Demos](https://kaltura.github.io/intelligent-agents-sdk/guides/live-demos/index.md) | | See a complete browser example with a live avatar | [examples/browser-experience.html](https://github.com/kaltura/intelligent-agents-sdk/blob/main/examples/browser-experience.html) | | See a complete avatar-guided slide deck | [examples/deck-presenter.html](https://github.com/kaltura/intelligent-agents-sdk/blob/main/examples/deck-presenter.html) | | Let the avatar see the user's screen | [examples/screen-share-agent.html](https://github.com/kaltura/intelligent-agents-sdk/blob/main/examples/screen-share-agent.html) | --- ## 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](https://kaltura.github.io/intelligent-agents-sdk/reference/api/management-operations/index.md) 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](https://kaltura.github.io/intelligent-agents-sdk/reference/api/management-operations/index.md) 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: [''] } })`. Details under [Create an Agent](https://kaltura.github.io/intelligent-agents-sdk/reference/api/build/avatar-and-agent/index.md#create-an-agent). **Can I use my own face or voice?** Yes, both. See [Catalog & Assets](https://kaltura.github.io/intelligent-agents-sdk/reference/api/design/index.md#upload-a-custom-visual-portrait--animated-avatar) (visual) and [→ Custom Voice](https://kaltura.github.io/intelligent-agents-sdk/reference/api/design/index.md#upload-a-custom-voice-clone).