Create and Configure an Intellect

← Back to Agent Components

An intellect is the config object that drives your agent. It holds the prompts, model settings, tools, knowledge base links, and feature capabilities that shape how the agent behaves. This page shows how to create one and configure its main fields.

Generate an Agent Profile

Optional first step: turn a one-line description into the prompt values an intellect needs.

POST https://api.avatar.us.kaltura.ai/v1/application/generateAgentProfile

{ "userDescription": "A friendly technical support agent for a video platform" }

Returns {goal, targetAudience, restrictedTopics, name, openingPhrase}. Nothing is saved: pass goal, targetAudience and restrictedTopics into the intellect's prompts and openingPhrase into the intellect's opening_phrase (§ Configure an Intellect, below). Leave the avatar's own openingPhrase unset (Agent Components · Create an Avatar and an Agent).

Create an Intellect

POST https://genie.nvp1.ovp.kaltura.com/v1/intellect/add

{ "type": "internal", "status": 2 }

Returns the full intellect object. Save id. It is your configId.

External LLM (BYO-LLM). It is possible, but not self-serve. Ask your Kaltura Account Manager to set it up. intellects.create rejects a body that contains url or protocol with a typed bad_request.

Configure an Intellect

POST https://genie.nvp1.ovp.kaltura.com/v1/intellect/update

{
  "id": 1389,
  "type": "internal",
  "status": 2,
  "prompts": [
    {
      "key": "goal",
      "label": "Goal",
      "headerTemplate": "Your core strategic goal:",
      "type": "custom",
      "value": "Help users troubleshoot video streaming issues"
    }
  ],
  "base_directive": "You are StreamBot. Be concise and technically accurate.",
  "capabilities": {
    "avatar": "on",
    "generate_followup_questions": "on",
    "use_knowledge_base": "off"
  }
}

Prompts. Each block adds a section to the system prompt:

lintPrompts reports a missing type as the warning missing_type and any value other than the three above as bad_type. A block whose headerTemplate or value is empty or only whitespace is skipped. It adds nothing to the prompt, and lintPrompts warns renderer_skip.

Call mgmt.application.getCustomPrompts(ks) to get the key and headerTemplate values. It returns the current schema for this block: a 5-entry array (goal, targetAudience, restrictedTopics, name, knowledge), each shaped as {key, label, headerTemplate, type} (every entry returned has type: "custom"; your own blocks can use any of the three type values above).

Use this call to render a "describe your agent" form. The labels and instructions you show always match the current prompt blocks, so you do not keep hardcoded copy in sync by hand.

This call only reads data and has no side effects. It works with any kind of session token.

const fields = await mgmt.application.getCustomPrompts(ks);
// [{ key: 'goal', label: 'Goal', headerTemplate: 'The agent\'s goal is: {{value}}', type: 'custom' }, ...]

Top-level fields:

Conditions

A condition switches a skill, a prompt block or a tool on only while it is true. It is a bare expression over thread variables:

await mgmt.intellectConfig.setSkillIds(configId, [
  { id: skill.id, mode: 'preloaded', condition: 'sys__avatar_enabled and not sys__avatar_share_screen_enabled' },
], ks);

Do not wrap it in {{ }}, {% %} or {# #}. The server answers a template-style condition with an empty reply and no error. The SDK rejects the delimiters on write, lintPrompts reports bad_condition, and intellectConfig.audit flags a saved one.

Variables you can use: the sys__* variables in Reserved Template Variables, and any variable a var tool has set. A var tool value is visible from the next turn of the same thread, not the same turn. The later call wins, and a new thread does not see it.

Condition grammar

The server evaluates the expression. An unknown name is falsy, with no error. Request variables sent with the call are text. A var tool int arg keeps its type.

Guard an ordering compare: visits is defined and visits > 2. The SDK warns about the empty-reply forms: suspect_condition from lintPrompts, and prompt_suspect_condition, skill_condition_suspect and tool_condition_suspect from intellectConfig.audit. previewPrompt does not evaluate conditions, so check a new condition with one live turn.

Capabilities

Each is "on" / "off" / "disabled":

When you set capabilities directly, send the full dict. To change one key, use mgmt.intellects.setCapability. It reads the current dict and re-sends it with your change.

Note: force_experience is not an intellect field. It is a per-call option on converse() (values "markdown", "summarization", "flashcards", "avatar_only"; a hint, not a guarantee). See Converse.

Related docs