Get Started

An Omniagent is a single AI agent with a consistent voice, personality, knowledge, and memory — available on any channel. Define it once, deploy it to web, WebSocket, or phone. Update it once, every channel picks up the change.

This guide walks you through building the pieces and assembling them into your first Omniagent.

Pick a companion

The companion defines your agent's identity — how it looks and behaves. Browse the catalog of pre-built companions and pick an id from the results:

curl https://companion-api.napster.com/public/companions/napster-stock?pageSize=10 \
  -H "X-Api-Key: $NAPSTER_API_KEY"

If none of the catalog companions fit your use case, create a custom one with your own personality and avatar:

curl -X POST https://companion-api.napster.com/public/companions \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alex",
    "lastName": "Chen",
    "description": "A senior tech support specialist. Warm, patient, and detail-oriented. Explains technical concepts in plain language.",
    "pictureUrl": "https://example.com/images/alex-avatar.png"
  }'

Save the id from the response — you'll need it when creating the agent.

For the full set of companion options (gender, ethnicity, personality), see Companion.

Add tools (optional)

Tools let your agent take actions during conversations — look up orders, book appointments, trigger workflows. Create a tool by defining what it does and where it executes:

curl -X POST https://companion-api.napster.com/public/functions \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "get_order_status",
      "description": "Look up the current status of a customer order by order ID",
      "parameters": {
        "type": "object",
        "properties": {
          "orderId": {
            "type": "string",
            "description": "The order ID to look up"
          }
        },
        "required": ["orderId"]
      }
    },
    "url": "https://your-server.com/api/order-status",
    "flow": "explicit"
  }'

Save the id from the response. You can create as many tools as you need.

For details on execution flows (implicit vs explicit), tool prompts, and responding to tool calls, see Tools.

Add knowledge (optional)

Give your agent domain expertise so it can answer questions using your content instead of relying solely on the base LLM.

Upload documents — create a knowledge collection and upload files:

# Create a collection
curl -X POST https://companion-api.napster.com/public/knowledge-bases \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Docs"
  }'

# Upload a file to the collection
curl -X POST https://companion-api.napster.com/public/knowledge-bases/kb_abc123/files \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/docs/product-guide.pdf"
  }'

Add FAQs — for questions where you need a specific, controlled answer:

# Create an FAQ collection
curl -X POST https://companion-api.napster.com/public/faqs \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support FAQs"
  }'

# Add a Q&A pair
curl -X POST https://companion-api.napster.com/public/faqs/faq_abc123/items \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is your return policy?",
    "answer": "You can return any item within 30 days of purchase for a full refund."
  }'

Save the collection IDs. For more on knowledge and FAQs, see Files and FAQs.

Create the Omniagent

Now bring everything together. Pass the companion ID, voice, and any tools, knowledge, and FAQs you created in the previous steps:

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",
    "language": "English",
    "functions": ["fn_abc123"],
    "faqCollections": ["faq_abc123"],
    "knowledgeBaseId": "kb_abc123",
    "providerSettings": {
      "temperature": 0.7
    }
  }'

Parameter	Type	Required	Description
`companionId`	string	Yes	The companion from step 1.
`voiceId`	string	Yes	The voice for speech output (e.g. `alloy`, `echo`, `shimmer`).
`providerSettings`	object	Yes	Model and audio settings. See Configuration.
`name`	string	No	A label for this agent.
`language`	string	No	Lock to a specific language (e.g. `English`, `Spanish`). Defaults to English.
`functions`	string[]	No	Tool IDs from step 2.
`faqCollections`	string[]	No	FAQ collection IDs from step 3.
`knowledgeBaseId`	string	No	Knowledge collection ID from step 3.

Your Omniagent is ready. The id in the response is what you use to deploy it.

Get Started

Pick a companion

Add tools (optional)

Add knowledge (optional)

Create the Omniagent

What's next

Channels

Configuration

Managing your agent

On this page