Skip to main content

​
Choosing the Right Agent Type

iwy offers two types of agents:
TypeBest ForSessions per AgentVisible in Dashboard
Single-Use (you are here)Personalized, per-session experiences1No
PermanentReusable agents with dashboard managementUnlimitedYes
Not sure which to use? See the full comparison. Both are production-ready.

​
Overview

Single-Use agents are created via API and can only be activated once. After the session ends (or TTL expires), the agent ID becomes invalid. This is ideal for:
  • Personalized experiences: Create a unique agent for each user or session
  • Dynamic configuration: Generate agent settings from your database or user context
  • Auto-cleanup: No manual deletion needed—agents expire automatically
  • White-label solutions: Build products where end-users don’t see the iwy dashboard

​
How It Works

  1. Define your agent in code - Specify LLM, voice, avatar, and behavior via API
  2. Receive an agent ID - Use this ID in your frontend widget
  3. Agent auto-expires - No cleanup needed, agents expire after the TTL

​
Authentication

All API endpoints require authentication using a Bearer token. You can find your API key in your account settings. 
Authorization: Bearer YOUR_API_KEY

​
Base URL

https://api.iwy.ai/v1

​
Quick Start

Create an ephemeral agent and embed it in your app: 
curl -X POST https://api.iwy.ai/v1/ephemeral-agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "llm": {
        "model": "gemini-2.0-flash",
        "provider": "google",
        "system_prompt": "You are a helpful assistant for a product demo",
        "first_message": "Welcome! How can I help you today?"
      },
      "tts": {
        "provider": "elevenlabs",
        "voice_id": "21m00Tcm4TlvDq8ikWAM"
      },
      "video": {
        "provider": "binary",
        "character_id": "0001"
      }
    },
    "ttl_seconds": 600
  }'
Response: 
{
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440099",
    "expires_at": "2025-01-15T10:30:00.000Z",
    "created_at": "2025-01-15T10:20:00.000Z"
  }
}
Then embed the agent in your frontend: 
<live-avatar agentid="550e8400-e29b-41d4-a716-446655440099"></live-avatar>
<script src="https://unpkg.com/@iwy/live-widgets@latest/dist/live-avatar.min.js"></script>

​
When to Use Single-Use vs Permanent

Use CaseRecommended
Prototyping and testingPermanent
Same agent for all usersPermanent
Personalized agent per user/sessionSingle-Use
Config generated from your databaseSingle-Use
Production systemsBoth

​
Support

Need help? Contact us