Runway Characters integration guide | LiveKit Documentation

Available in

Python

Node.js

Overview

Runway Characters provides photorealistic and animated characters with full conversational expressiveness. You can use the open source Runway integration for LiveKit Agents to add digital avatars to your voice AI app.

Installation

uv add "livekit-agents[runway]~=1.5"

pnpm add @livekit/agents-plugin-runway

Authentication

The Runway plugin requires a Runway API key.

Set RUNWAYML_API_SECRET in your .env file.

Avatar setup

The Runway plugin requires either a custom avatar ID or preset avatar ID. They are mutually exclusive and can be passed in the avatar session via avatar_id and preset_id respectively. You can browse and create characters in the Runway developer portal.

Select either an avatar ID or preset avatar ID for the following steps.

Note

LiveKit TTS settings will supersede selected voices and personalities configured for the Runway character.

Usage

Use the plugin in an AgentSession. For example, you can use this avatar in the Voice AI quickstart.

from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import runway

server = AgentServer()

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        # ... stt, llm, tts, etc.
    )

    avatar = runway.AvatarSession(
        avatar_id="...",  # ID of the custom Runway character to use
    )

    # Start the avatar and wait for it to join
    await avatar.start(session, room=ctx.room)

    # Start your agent session with the user
    await session.start(
        # ... room, agent, room_options, etc....
    )

import { voice } from '@livekit/agents';
import * as runway from '@livekit/agents-plugin-runway';

const session = new voice.AgentSession({
   // ... stt, llm, tts, etc.
});

const avatar = new runway.AvatarSession({
   avatarId: '...',  // ID of the custom Runway character to use
});

// Start the avatar and wait for it to join
await avatar.start(session, room);

// Start your agent session with the user
await session.start({
   // ... room, agent, room_options, etc.
});