Agent Configuration

When you create an Omniagent, you define everything about how it behaves — its identity, resources, voice, language, and model settings. These apply consistently across every channel the agent is deployed to.

This page is the complete reference for all agent-level settings.

Setting and updating configuration

Every field on this page can be set when you create the agent or updated later. Only the fields you include are changed — everything else stays the same.

Create an agent with your initial configuration:

curl -X POST https://companion-api.napster.com/public/agents \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companionId": "comp_abc123",
    "name": "Support Agent",
    "voiceId": "alloy",
    "providerSettings": {
      "temperature": 0.7
    }
  }'

Update any field later with a PATCH request — only include what you want to change:

curl -X PATCH https://companion-api.napster.com/public/agents/agent_abc123 \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "Spanish",
    "voiceId": "shimmer"
  }'

Identity

These fields define who your agent is.

Name

An optional label to identify agents in your project — for example, "Support Agent", "Sales Bot", or "Onboarding Assistant".

Companion

The companionId is required and determines the agent's visual appearance, personality, and behavior. See Companion for how to pick or create one.

Language

When you set language, the agent strictly follows that language for the entire session — it will not switch even if the user speaks in a different language. Use plain language names — English, Spanish, French, German, etc. — not ISO codes.

If you omit language, the agent defaults to English but can switch to a different language when the user asks.

{
  "companionId": "comp_abc123",
  "name": "Support Agent",
  "language": "English"
}

Knowledge

Knowledge gives your agent domain expertise through two types of resources.

Documents

The knowledgeBaseId field attaches a knowledge collection to the agent. The agent retrieves relevant documents from this collection during conversations to ground its responses in your content. See Files for details.

FAQs

The faqCollections field accepts an array of FAQ collection IDs. When a user asks a question that matches one of your FAQs, the agent responds with the answer you defined rather than generating one. See FAQs for details.

{
  "knowledgeBaseId": "kb_product_docs",
  "faqCollections": ["faq_support", "faq_returns"]
}

Tools

The functions field accepts an array of tool IDs. These define what your agent can do during conversations — look up data, trigger workflows, generate content. You can attach as many tools as you need.

Tools must be created before attaching them to the agent. See Tools for details.

{
  "functions": ["fn_order_status", "fn_returns", "fn_book_appointment"]
}

Tags

The tags field accepts string-to-string key-value pairs for labeling the agent. Use tags to categorize agents by source, environment, team, or any dimension relevant to your application. Tags are stored on the agent and returned on all sessions created from it.

{
  "tags": {
    "env": "production",
    "team": "support",
    "source": "ios-app"
  }
}

Tag keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

Idle timeout

By default, idle sessions are automatically closed after a timeout. Set disableIdleTimeout to true on the agent to keep all sessions open indefinitely, even if no audio or messages are exchanged.

{
  "disableIdleTimeout": true
}

Voice

The voiceId field is required and sets the voice for the agent's speech output.

{
  "voiceId": "alloy"
}

Provider settings

The providerSettings object controls model behavior and audio processing.

{
  "providerSettings": {
    "temperature": 0.7,
    "turnDetection": {
      "threshold": 0.9,
      "prefix_padding_ms": 400,
      "silence_duration_ms": 500
    },
    "noiseReduction": {
      "type": "nearField"
    }
  }
}

Turn detection

The turnDetection object configures Voice Activity Detection (VAD) — how the system decides when the user has started and stopped speaking. This directly affects interruption behavior and response timing.

Noise reduction

The noiseReduction object accepts a single type field:

Channel overrides

All of the settings above apply across every channel by default. If you need different behavior on a specific channel, you can override providerSettings, functions, faqCollections, and knowledgeBaseId per channel using the channel config.

For example, to use different turn detection settings and attach an additional tool on SIP calls:

curl -X PUT https://companion-api.napster.com/public/agents/agent_abc123/channels/sip \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "functions": ["fn_order_status", "fn_returns", "fn_transfer_call"],
    "providerSettings": {
      "turnDetection": {
        "threshold": 0.7,
        "silence_duration_ms": 800
      }
    }
  }'

Channel overrides apply to every session on that channel. If omitted, the agent's base configuration is used. See the SIP, WebRTC, and WebSockets guides for channel-specific setup.