Single-Use Agents

Choosing the Right Agent Type

iwy offers two types of agents:

Type	Best For	Sessions per Agent	Visible in Dashboard
Single-Use (you are here)	Personalized, per-session experiences	1	No
Permanent	Reusable agents with dashboard management	Unlimited	Yes

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

Define your agent in code - Specify LLM, voice, avatar, and behavior via API
Receive an agent ID - Use this ID in your frontend widget
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 Case	Recommended
Prototyping and testing	Permanent
Same agent for all users	Permanent
Personalized agent per user/session	Single-Use
Config generated from your database	Single-Use
Production systems	Both

Support

Need help? Contact us

API Reference

Permanent Agents

Tools

Sessions

Single-Use Agents

Choosing the Right Agent Type

Overview

How It Works

Authentication

Base URL

Quick Start

When to Use Single-Use vs Permanent

Support

​Choosing the Right Agent Type

​Overview

​How It Works

​Authentication

​Base URL

​Quick Start

​When to Use Single-Use vs Permanent

​Support

Choosing the Right Agent Type

Overview

How It Works

Authentication

Base URL

Quick Start

When to Use Single-Use vs Permanent

Support