🤖 Agent Service

An agent is where everything comes together — it's the character your users will talk to.

An agent links an avatar (the face and voice) with an intelligence engine (the AI backend that understands and responds), and defines how the conversation should behave. Once an agent is configured here, the Control API can spin up real-time sessions backed by it.

Base route: POST /service/agent/action/{actionName}

Data Model

Agent
├── agentId           string (UUID)
├── displayName       string
├── intellect
│   ├── intellectType   'genie' | 'external'
│   ├── configId        number
│   └── genieId         string
├── avatarIds         string[]
├── maxConversationLength  number (1–3600s)
├── widgetConfig
│   ├── initialPage.title  string
│   └── layouts.avatar / layouts.chat  boolean
├── embedConfig
│   └── theme         string
├── adminTags         string[]
├── partnerId         number
├── createdAt / updatedAt  Date
└── createdBy         string

Agent Fields

Field	Type	Description
`agentId`	string (UUID)	Unique identifier for the agent
`displayName`	string	Human-readable name for the agent
`intellect`	object	The AI engine configuration (see below)
`avatarIds`	string[]	IDs of avatars assigned to this agent
`maxConversationLength`	number	Max session length in seconds (1–3600)
`widgetConfig`	object	Widget UI configuration (optional)
`embedConfig`	object	Embed theme configuration (optional)
`legacyScreenShare`	object	Screen share settings (optional)
`adminTags`	string[]	Tags for filtering and organization
`partnerId`	number	Your Kaltura partner ID
`createdAt`	Date	Creation timestamp
`updatedAt`	Date	Last modification timestamp
`createdBy`	string	User ID who created the agent

Intellect Configuration

What's an "intellect"?

The intellect defines the AI engine that powers the agent's conversations. Currently two types are supported:

genie — Kaltura's built-in conversational AI engine. Provide a configId that references an intellect created via the 🧠 Intellect Service. The intellect controls prompts, glossary, capabilities, and can attach a 📚 Knowledge base.
external — An external AI backend. Provide a configId that references your external configuration.

Field	Type	Required	Description
`intellectType`	`'genie'` \| `'external'`	✅ Yes	The type of intelligence engine
`configId`	number	✅ Yes	Intellect partner config ID — see 🧠 Intellect Service
`genieId`	string	✅ Yes	Genie instance ID

Controls how the embedded chat widget looks and behaves:

Field	Type	Description
`widgetConfig.initialPage.title`	string (max 30 chars)	Title shown on the widget's initial screen
`widgetConfig.layouts.avatar`	boolean	Whether to show the avatar in the widget
`widgetConfig.layouts.chat`	boolean	Whether to show the chat panel

Embed Configuration

Field	Type	Description
`embedConfig.theme`	string	Visual theme for the embedded widget

Actions

`get` — Retrieve an Agent

POST /service/agent/action/get

Request body:

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
`agentId`	string	✅ Yes	The UUID of the agent to retrieve

Response:

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "Customer Support Assistant",
  "intellect": {
    "intellectType": "genie",
    "genieId": "genie_abc123",
    "configId": 42
  },
  "avatarIds": ["64f1a2b3c4d5e6f7a8b9c0d1"],
  "maxConversationLength": 1800,
  "adminTags": ["production", "support"],
  "partnerId": 12345,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T14:22:00.000Z",
  "createdBy": "admin@company.com"
}

Examples:

cURL
curl -X POST "https://YOUR_API_HOST/service/agent/action/get" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "550e8400-e29b-41d4-a716-446655440000"
  }'

JavaScript
const agent = await fetch('https://YOUR_API_HOST/service/agent/action/get', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agentId: '550e8400-e29b-41d4-a716-446655440000',
  }),
}).then((res) => res.json());

console.log(`Agent: ${agent.displayName}`);

Error responses:

Status	Description
`401`	Invalid or expired KS token
`404`	Agent not found

`list` — List Agents

POST /service/agent/action/list

Retrieve a paginated list of agents, with optional filtering.

Request body:

{
  "filter": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "adminTagsIn": ["production"]
  },
  "pager": {
    "offset": 0,
    "limit": 30
  },
  "orderBy": "-createdAt"
}

Field	Type	Required	Description
`filter.agentId`	string	No	Filter to a specific agent ID
`filter.adminTagsIn`	string[]	No	Filter by any of these admin tags
`pager.offset`	number	No	Pagination offset (default: 0)
`pager.limit`	number	No	Max results per page (default: 30)
`orderBy`	string	No	Sort order: `+createdAt`, `-createdAt`, `+updatedAt`, `-updatedAt`

Response:

{
  "objects": [
    {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Customer Support Assistant",
      ...
    }
  ],
  "totalCount": 5
}

Examples:

cURL — list all agents, newest first
curl -X POST "https://YOUR_API_HOST/service/agent/action/list" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pager": { "offset": 0, "limit": 30 },
    "orderBy": "-createdAt"
  }'

JavaScript — list agents with tag filter
const { objects, totalCount } = await fetch('https://YOUR_API_HOST/service/agent/action/list', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { adminTagsIn: ['production'] },
    pager: { offset: 0, limit: 30 },
    orderBy: '-createdAt',
  }),
}).then((res) => res.json());

console.log(`Found ${totalCount} production agents`);

`create` — Create an Agent

POST /service/agent/action/create

Request body:

{
  "displayName": "Customer Support Assistant",
  "intellect": {
    "intellectType": "genie",
    "genieId": "genie_abc123",
    "configId": 42
  },
  "avatarIds": ["64f1a2b3c4d5e6f7a8b9c0d1"],
  "maxConversationLength": 1800,
  "adminTags": ["production"],
  "widgetConfig": {
    "initialPage": {
      "title": "How can I help?"
    },
    "layouts": {
      "avatar": true,
      "chat": true
    }
  }
}

Field	Type	Required	Description
`displayName`	string	No	Human-readable name
`intellect`	object	✅ Yes	AI engine config (see Intellect Configuration)
`avatarIds`	string[]	No	Avatar IDs to assign to this agent
`maxConversationLength`	number	No	Max session length in seconds (1–3600)
`adminTags`	string[]	No	Tags for filtering
`widgetConfig`	object	No	Widget UI settings
`embedConfig`	object	No	Embed theme settings
`legacyScreenShare`	object	No	Screen share settings

Response: Returns the created Agent object with the generated agentId.

Examples:

cURL
curl -X POST "https://YOUR_API_HOST/service/agent/action/create" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Customer Support Assistant",
    "intellect": {
      "intellectType": "genie",
      "genieId": "genie_abc123",
      "configId": 42
    },
    "avatarIds": ["64f1a2b3c4d5e6f7a8b9c0d1"],
    "maxConversationLength": 1800
  }'

JavaScript
const newAgent = await fetch('https://YOUR_API_HOST/service/agent/action/create', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    displayName: 'Customer Support Assistant',
    intellect: {
      intellectType: 'genie',
      genieId: 'genie_abc123',
      configId: 42,
    },
    avatarIds: ['64f1a2b3c4d5e6f7a8b9c0d1'],
    maxConversationLength: 1800,
  }),
}).then((res) => res.json());

// 🎉 Your agent is alive!
console.log(`Created agent: ${newAgent.agentId}`);

Error responses:

Status	Description
`400`	Invalid request body (e.g., missing required `intellect`)
`401`	Invalid or expired KS token

`update` — Update an Agent

POST /service/agent/action/update

Update a subset of an agent's fields. Only include fields you want to change — omitted fields remain unchanged.

Request body:

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "Updated Assistant Name",
  "avatarIds": ["64f1a2b3c4d5e6f7a8b9c0d2"],
  "maxConversationLength": 3600
}

Field	Type	Required	Description
`agentId`	string	✅ Yes	The agent to update
`displayName`	string	No	New display name
`avatarIds`	string[]	No	Replace the full list of avatar IDs
`maxConversationLength`	number	No	New max length in seconds (1–3600)
`adminTags`	string[]	No	Replace the full list of admin tags
`widgetConfig`	object	No	New widget configuration
`embedConfig`	object	No	New embed configuration
`legacyScreenShare`	object	No	New screen share settings

Arrays are replaced, not merged

When you pass avatarIds or adminTags, the entire array is replaced. To add one avatar ID, fetch the current list first and include all existing IDs plus the new one.

Response: Returns the updated Agent object.

Examples:

cURL
curl -X POST "https://YOUR_API_HOST/service/agent/action/update" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "maxConversationLength": 3600
  }'

JavaScript
const updatedAgent = await fetch('https://YOUR_API_HOST/service/agent/action/update', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agentId: '550e8400-e29b-41d4-a716-446655440000',
    maxConversationLength: 3600,
  }),
}).then((res) => res.json());

`delete` — Delete an Agent

POST /service/agent/action/delete

Permanently deletes an agent. This cannot be undone.

Request body:

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
`agentId`	string	✅ Yes	The agent to delete

Response:

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}

Examples:

cURL
curl -X POST "https://YOUR_API_HOST/service/agent/action/delete" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "550e8400-e29b-41d4-a716-446655440000"
  }'

JavaScript
await fetch('https://YOUR_API_HOST/service/agent/action/delete', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agentId: '550e8400-e29b-41d4-a716-446655440000',
  }),
});

Error responses:

Status	Description
`401`	Invalid or expired KS token
`404`	Agent not found

`getEmbedScript` — Get an Embeddable HTML Snippet

POST /service/agent/action/getEmbedScript

The fastest way to put your agent in front of end users. Call this with an agentId and paste the returned HTML into any webpage — no further configuration needed.

The response contains a <div> container and an inline <script> that loads the Unisphere widget, resolves the agent's Kaltura widget ID (creating one automatically if it doesn't exist), and initialises the chat interface.

Request body:

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
`agentId`	string (UUID)	✅ Yes	The agent to generate an embed script for

Response:

{
  "html": "<div id='genie-container' style='width: 100%; height: 100vh'></div><script type='module'>...</script>"
}

Examples:

cURL
curl -X POST "https://YOUR_API_HOST/service/agent/action/getEmbedScript" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "550e8400-e29b-41d4-a716-446655440000" }'

JavaScript — fetch and inject embed
const { html } = await fetch(
  'https://YOUR_API_HOST/service/agent/action/getEmbedScript',
  {
    method: 'POST',
    headers: { 'Authorization': `KS ${ksToken}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ agentId: '550e8400-e29b-41d4-a716-446655440000' }),
  }
).then(res => res.json());

// Inject into your page
document.getElementById('agent-embed').innerHTML = html;

Drop-in vs. programmatic

getEmbedScript is the simplest delivery path — one API call, paste the HTML, done. If you need programmatic control over the session (say-text, interrupt, keep-alive), use the ⚡ Control API instead.

Usage Notes

Multiple Avatars per Agent

An agent can have multiple avatar IDs assigned via avatarIds. This allows the Control API to select which avatar personality to use when starting a session. If no specific avatar is requested at session creation time, the first avatar in the list is used.

widgetConfig — controls the layout and initial state of the built-in chat widget (the iframe-embeddable UI Kaltura provides)
embedConfig — controls visual theming when the widget is embedded in your site

If you're building a fully custom UI using the Control API directly, you can safely ignore both of these fields.

🧪 Advanced: Legacy Screen Share

The legacyScreenShare field enables an older screen sharing mode for the avatar session:

{
  "legacyScreenShare": {
    "enabled": true,
    "prompt": "You can see the user's screen. Describe what you observe."
  }
}

This injects the screen share prompt into the agent's conversation context when a screen share session is active. Use this if your integration relies on the legacy screen share mechanism.

Next Steps

🎭 Avatar Service — Create the avatars referenced by avatarIds
🧠 Intellect Service — Configure the AI behind your agent
🛠️ Workflows — See a complete agent setup from scratch
Embed your agent — call getEmbedScript and drop the returned HTML into any webpage
⚡ Control API — Programmatic server-side session control

🤖 Agent Service

Data Model

Agent Fields

Intellect Configuration

Widget Configuration

Embed Configuration

Actions

`get` — Retrieve an Agent

`list` — List Agents

`create` — Create an Agent

`update` — Update an Agent

`delete` — Delete an Agent

`getEmbedScript` — Get an Embeddable HTML Snippet

Usage Notes

Multiple Avatars per Agent

Widget vs. Embed Config

Next Steps

Data Model​

Agent Fields​

Intellect Configuration​

Widget Configuration​

Embed Configuration​

Actions​

get — Retrieve an Agent​

list — List Agents​

create — Create an Agent​

update — Update an Agent​

delete — Delete an Agent​

getEmbedScript — Get an Embeddable HTML Snippet​

Usage Notes​

Multiple Avatars per Agent​

Widget vs. Embed Config​

Next Steps​

Data Model

Agent Fields

Intellect Configuration

Widget Configuration

Embed Configuration

Actions

`get` — Retrieve an Agent

`list` — List Agents

`create` — Create an Agent

`update` — Update an Agent

`delete` — Delete an Agent

`getEmbedScript` — Get an Embeddable HTML Snippet

Usage Notes

Multiple Avatars per Agent

Widget vs. Embed Config

Next Steps