AI Companion

Overview

This article shows how to build an AI companion – a persistent conversational agent that remembers conversation over time.

What you’ll build

An AI companion that:

• Understands voice input
• Responds with natural speech
• Displays a synchronized avatar
• Uses a defined personality and context

Prerequisites

• TruGen API key
• (Optional) Knowledge base ID

Implementation steps

1. Send the request

curl --request POST \
  --url https://api.trugen.ai/v1/ext/agent \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "agent_name": "AI Companion
  "agent_system_prompt": "You are a friendly AI that answers questions.

# Conversational flow

- Help the user with any question that he has in a professional and safe way.
- Use the available tools when required, start by collecting required information and perform action silently.",

  "config": {
    "timeout": 240,
    "memory": {
      "isEnabled": true,
      "instruction": "Adapt memory capture to the configured memory‐depth level (surface, detailed, or deep) by adjusting the granularity of stored information.

1.Personal Identity and Relationships
  • Store names and roles (friends, family, pets).
  • At detailed depth, add birthdays, nicknames, relationship context.
  • At deep depth, note anecdotes, origin stories, and evolving dynamics.

2.Significant Memories and Experiences
  • Record event type (e.g., vacation, milestone).
  • At detailed depth, include dates, locations, participants.
  • At deep depth, capture emotions, lessons learned, sensory details.

3.Emotional State and Well-Being
  • Log mood indicators (happy, stressed, lonely).
  • At detailed depth, note triggers, coping strategies, support persons.
  • At deep depth, track patterns over time, recurring concerns, resilience factors.

3.Daily Activities and Routines
  • Capture recurring habits (sleep schedule, meals, exercise).
  • At detailed depth, record times, frequency, duration.
  • At deep depth, note deviations, motivations, energy levels, obstacles.

4.Preferences and Interests
  • Store favorites (music, movies, books, foods).
  • At detailed depth, include genres, artists, authors, flavors.
  • At deep depth, note evolving tastes, collection details, related aspirations.

5.Plans, Events, and Goals
  • Log upcoming commitments (appointments, trips, to-dos).
  • At detailed depth, add dates, locations, preparation steps.
  • At deep depth, record milestones, dependencies, anticipated challenges.

6 Communication and Social Preferences
  • Note preferred contact methods and times.
  • At detailed depth, include tone preferences, conversation topics.
  • At deep depth, track social energy patterns, ideal group sizes, feedback style.

For each category, ensure compliance with privacy settings and user consent before storing sensitive details."
    }
  },

  "knowledge_base": [
    {
      "id": "4a0365e4-ced5-42f0-8933-b6880a0ce044",
      "name": "new kb 123"
    }
  ],
  "record": true,
  "callback_url": "",
  "callback_events": [
    "participant_left",
    "max_call_duration_warning",
    "max_call_duration_timeout",
    "action_found"
  ],
  "avatars": [
    {
      "avatar_key_id": "665a1170",
      "config": {
        "llm": {
          "model": "meta-llama/llama-4-maverick-17b-128e-instruct",
          "provider": "groq"
        },
        "stt": {
          "model": "flux-general-en",
          "provider": "deepgram",
          "min_endpointing_delay": 0.3,
          "max_endpointing_delay": 0.4
        },
        "tts": {
          "model_id": "eleven_turbo_v2_5",
          "provider": "elevenlabs",
          "voice_id": "ZUrEGyu8GFMwnHbvLhv2"
        }
      },
      "persona_name": "AI Companion",
      "persona_prompt": "You're a helpful ai agent. Answer all questions appropriately.",
      "conversational_context": "Sample Conversational Context",
      "idle_timeout": {
        "timeout": 30,
        "filler_phrases": [
          "Hey it's been a while since we last spoke, are we still connected?",
          "I notice we haven't talked for a bit, is everything okay?"
        ]
      },
      "welcome_message": {
        "wait_time": 2,
        "messages": [
          "Hi, how are you doing today?",
          "Hello, how can I help you?"
        ]
      },
      "warning_exit_message": {
        "callout_before": 10,
        "messages": [
          "We are almost at the end of our call, thank you for your time.",
          "Thank you for your time. We will see you next time."
        ]
      },
      "exit_message": {
        "max_call_duration": 300,
        "messages": [
          "We are at the end of our call, thank you for your time.",
          "Thank you for your time today."
        ]
      },
      "exit_heads_up_message": {
        "callout_before": 10,
        "messages": [
          "We are almost at the end of our call, thank you for your time.",
          "Thank you for your time. We will see you next time."
        ]
      }
    }
  ]
}
EOF

This request creates a fully configured AI companion with voice, avatar, and conversational behavior.

2. Define the companion behavior

The configuration controls how the companion thinks and responds:

• agent_system_prompt → Core behavior and instructions
• memory → Whether the companion retains context
• timeout → Session duration

3. Add knowledge

"knowledge_base": [
    {
      "id": "4a0365e4-ced5-42f0-8933-b6880a0ce044",
      "name": "new kb 123"
    }
  ]

This allows the companion to respond using external information instead of only general knowledge.

4. Configure voice and intelligence

Inside the avatar configuration:

• llm → Language model (reasoning)
• stt → Speech-to-text (input)
• tts → Text-to-speech (output)

This defines how the companion listens, thinks, and speaks.

5. Define personality and interaction

"persona_name"
"persona_prompt"
"conversational_context"

These fields shape:

• Tone and personality
• Initial conversation context
• How the companion behaves in dialogue

6. Control conversation flow

Optional fields like:

• welcome_message → Initial greeting
• idle_timeout → Behavior during silence
• exit_message → Ending interaction

These help make the companion feel more natural and interactive.

7. Verify the response

After sending the request, you will receive a response:

{
  "id": "generated-agent-id",
  "message": "Agent created successfully"
}

• This confirms that your AI companion has been created.
• Save the returned id

Result

• A fully configured AI companion is created
• The companion can listen, respond, and speak
• Avatar and voice are synchronized
• The system behaves according to defined personality and context

Next steps

• Connect the companion to a UI (widget or iframe)
• Use with LiveKit for realtime interaction
• Customize personality and voice
• Attach different knowledge bases