# Use-Case Catalog

A "what can you build" catalog for orienting a new integration. Read it once, then use [Backend API Reference](https://kaltura.github.io/intelligent-agents-sdk/reference/api-reference/index.md) for the mechanism details behind each entry.

Each use case maps to a runnable script or example in this repo, or the equivalent SDK call:

- UC-1 has a quickstart script.
- UC-7 and UC-12 use the browser example app.

<div data-nova-target="use-case-catalog-table" data-nova-label="Use-Case Catalog: all 14 use cases mapped to SDK entry points">

| # | Use case | Key mechanism | Script / SDK entry point |
|---|----------|--------------|--------|
| UC-1 | **Agent Factory** | `generateAgentProfile` → `v1/intellect/add` → configure → `avatar/create` → `agent/create` → `resolveWidgetId` | `node quickstart/create-agent.mjs "Your brief"` |
| UC-2 | **Personalized Concierge** | Prompts with `{{firstName}}`/`{{plan}}` + `allow_client_variables:true`; pass `request_vars` per message | `mgmt.converse(configId, msg, { request_vars })` |
| UC-3 | **Memory Chatbot** | First `converse` returns `threadId`; pass it back (treat it as a secret). `v1/thread/get_transcripts` for the full record | `mgmt.converse(...)` + `mgmt.threads.list`/`transcript` |
| UC-4 | **GenUI Experiences** | `force_experience` hint + `capabilities`; render `unisphere-tool` segments by `metadata.runtimeName` | `mgmt.converse(...)` + `./experience/genui` |
| UC-5 | **Avatar Fleet / A-B Personas** | `avatar/create` variants sharing a voice/visual, `agent/update avatarIds` to swap | `mgmt.avatars.create(...)` + `mgmt.agents.update(...)` |
| UC-6 | **Quality / Feedback Loop** | Capture `messageId` from converse → `mgmt.feedback.add()` → `reportSummary` | `mgmt.feedback.add(...)` + `mgmt.messages.reportSummary(ks)` |
| UC-7 | **Interactive Video Avatar** | `resolveWidgetId` → widget KS → `appInit` → socket.io + WHEP runtime | `examples/browser-experience.html` |
| UC-8 | **Headless Streaming Text** | `assistant/converse` (`sse:true` or NDJSON); stream `type:"text"` chunks; store `threadId` per user server-side and treat it as a secret | `mgmt.converse(...)` (or `mgmt.conversations.stream(opts, ks)` directly) |
| UC-9 | **Custom Voice Clone** | `catalog-item/create` (multipart, `~6 s+` audio) → `itemId` → `avatar/create voice.id` | `mgmt.catalog.createVoice(...)` |
| UC-10 | **Slide-Deck Walkthrough** | Deck talking points in prompts; deterministic `navigate_to_slide` client-command tool call for nav; optional GenUI widget via `show_widget` | `examples/deck-presenter.html` |
| UC-11 | **Usage Analytics** | Aggregated client-side; includes `_meta` provenance receipt | `mgmt.messages.reportSummary(ks)` |
| UC-12 | **Anonymous End-User Embed** | `resolveWidgetId` once (server) → `sessions.createWidgetToken` (browser, no secret) → `appInit` → enriched KS. To separate users: [per-visitor path](https://kaltura.github.io/intelligent-agents-sdk/reference/api/deploy/index.md#per-visitor-browser-path) | `examples/browser-experience.html` |
| UC-13 | **Custom Portrait Avatar** | `catalog-item/create` with portrait JPEG → `catalogItemId` → `avatar/create visual.id` → `appInit` → `KalturaAvatarSession` connects with the portrait animating live | [§ End-to-end recipe](https://kaltura.github.io/intelligent-agents-sdk/reference/api/design/index.md#end-to-end-custom-portrait-avatar-server-to-browser) |
| UC-14 | **Screen-Share Debugging Assistant** | Agent `screenShare` setting on with a prompt that says what to report → `session.startScreenShare()` sends a still every 2 seconds → the avatar answers about the user's code, error or app | `examples/screen-share-agent.html` |

</div>

## Composition patterns

| Pattern | Built from |
|---------|-----------|
| Knowledge-grounded support bot | UC-3 + `capabilities.use_knowledge_base:on` + [§ Ground the Agent](https://kaltura.github.io/intelligent-agents-sdk/reference/api/build/knowledge-rag/index.md#ground-the-agent-in-your-content-rag) |
| Multi-brand personas | UC-5 (voice) + UC-2 (`{{locale}}` var) |
| Lead-capture avatar | UC-7 + `user_properties_forms` |
| Scheduled / proactive avatar | UC-7 + your scheduler calls `session.speak(text)` on the `KalturaAvatarSession` |