Keyframe virtual avatar integration guide

uv add "livekit-agents[keyframe]~=1.4"

avatar = keyframe.AvatarSession(
    persona_slug="public:cosmo_persona-1.5-live",
)

avatar = keyframe.AvatarSession(
    persona_id="ab85a2a0-0555-428d-87b2-ff3019a58b93",
)

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

server = AgentServer()

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

    avatar = keyframe.AvatarSession(
        persona_slug="public:cosmo_persona-1.5-live",  # or use persona_id. See "Persona setup" for details.
    )

    # 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.
    )

await avatar.set_emotion("happy")  # "neutral", "happy", "sad", "angry"

from livekit.agents import Agent, RunContext, function_tool
from livekit.plugins.keyframe import Emotion

class AvatarAgent(Agent):
    def __init__(self, avatar: keyframe.AvatarSession) -> None:
        super().__init__(
            instructions=(
                "You are a friendly voice assistant with an avatar. "
                "Use the set_emotion tool to change your facial expression "
                "whenever the conversation mood shifts."
            ),
        )
        self._avatar = avatar

    @function_tool()
    async def set_emotion(self, context: RunContext, emotion: Emotion) -> str:
        """Set the avatar's facial expression to match the conversation mood.

        Args:
            emotion: The emotion to express. One of 'neutral', 'happy', 'sad', or 'angry'.
        """
        await self._avatar.set_emotion(emotion)
        return f"Emotion set to {emotion}"