LiveKit docs › Models › Virtual avatar › Runway

---

# Runway Characters integration guide

> How to use the Runway virtual avatar plugin for LiveKit Agents.

Available in:
- [x] Node.js
- [x] Python

## Overview

[Runway Characters](https://runwayml.com/product/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

**Python**:

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

```

---

**Node.js**:

```shell
pnpm add @livekit/agents-plugin-runway

```

### Authentication

The Runway plugin requires a [Runway API key](https://docs.dev.runwayml.com/guides/setup/#create-a-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](https://dev.runwayml.com/).

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](https://docs.livekit.io/agents/start/voice-ai.md).

**Python**:

```python
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....
    )

```

---

**Node.js**:

```typescript
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.
});

```

Preview the avatar in the [Agent Console](https://docs.livekit.io/agents/start/console.md) or a frontend [starter app](https://docs.livekit.io/agents/start/frontend.md#starter-apps) that you build.

### Parameters

This section describes some of the available parameters. See the [plugin reference](https://docs.livekit.io/reference/python/livekit/plugins/runway/index.html.md#livekit.plugins.runway.AvatarSession) for a complete list of all available parameters.

- **`avatar_id`** _(string)_ (optional): ID of the custom Runway character to use. See [Avatar setup](#avatar) for details.

- **`max_duration`** _(string)_ (optional): Maximum session duration in seconds.

- **`preset_id`** _(string)_ (optional): ID of the preset Runway character to use. See [Avatar setup](#avatar) for details.

## Additional resources

The following resources provide more information about using Runway with LiveKit Agents.

- **[Runway docs](https://docs.dev.runwayml.com/)**: Runway's full docs site.

- **[Agent Console](https://docs.livekit.io/agents/start/console.md)**: A virtual workbench to test your avatar agent.

- **[Frontend starter apps](https://docs.livekit.io/agents/start/frontend.md#starter-apps)**: Ready-to-use frontend apps with avatar support.

---

This document was rendered at 2026-04-30T22:31:08.248Z.
For the latest version of this document, see [https://docs.livekit.io/agents/models/avatar/plugins/runway.md](https://docs.livekit.io/agents/models/avatar/plugins/runway.md).

To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).