Quick Start - Documentation

Step 1 — Install and configure

pip install pipecat-ai[agenthuman]

Add your AgentHuman API key to your .env file, along with any STT, LLM, and TTS services you plan to use:

AGENTHUMAN_API_KEY=ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Example services (use whichever LLM / STT / TTS you prefer)
DAILY_ROOM_URL=https://your-domain.daily.co/your-room
DAILY_TOKEN=your-daily-participant-token
DEEPGRAM_API_KEY=your-deepgram-key
GOOGLE_API_KEY=your-google-ai-key
ELEVENLABS_API_KEY=your-elevenlabs-key

Step 2 — Set up your transport with video output

AgentHumanVideoService requires a transport with video_out_enabled=True. The transport dimensions are used to auto-select the avatar’s aspect ratio.

from pipecat.transports.daily.transport import DailyParams, DailyTransport

transport = DailyTransport(
    room_url=os.getenv("DAILY_ROOM_URL"),
    token=os.getenv("DAILY_TOKEN"),
    bot_name="AI Avatar",
    params=DailyParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        video_out_enabled=True,    # required
        video_out_is_live=True,
        video_out_width=1280,
        video_out_height=960,
        video_out_bitrate=2_000_000,
    ),
)

Step 3 — Add `AgentHumanVideoService` to your pipeline

Import AgentHumanVideoService and NewSessionRequest from pipecat.services.agenthuman, instantiate the service with your avatar ID and transport, and place it in the pipeline after TTS and before transport.output().

from pipecat.services.agenthuman.api import NewSessionRequest
from pipecat.services.agenthuman.video import AgentHumanVideoService

agentHuman = AgentHumanVideoService(
    api_key=os.getenv("AGENTHUMAN_API_KEY"),
    session_request=NewSessionRequest(
        avatar="avat_01KMZHXFPBVCXA5ATK85HCP8G1"  # your avatar ID
    ),
    transport=transport,
)

pipeline = Pipeline([
    transport.input(),
    stt,
    user_aggregator,
    llm,
    tts,
    agentHuman,          # ← place after TTS
    transport.output(),
    assistant_aggregator,
])

Step 4 — Run your bot

task = PipelineTask(pipeline, params=PipelineParams(enable_metrics=True))

@transport.event_handler("on_client_connected")
async def on_client_connected(transport, client):
    context.add_message({"role": "user", "content": "Say hello and briefly introduce yourself."})
    await task.queue_frames([LLMRunFrame()])

@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, client):
    await task.cancel()

runner = PipelineRunner()
await runner.run(task)

python bot.py

AgentHumanVideoService creates the AgentHuman session and connects to the internal LiveKit room automatically on pipeline start. You don’t need to manage room tokens or WebSocket connections manually.