@animated-waffle/react

React hook and Avatar renderer for embedding a published Narya talking Agent. This package depends on and re-exports the whole of @animated-waffle/client, so React applications install only this package.

The Agent owns its avatar, voice, and prompt. Pipecat, Daily, API routes, and avatar asset URLs are SDK implementation details. The renderer loads the Avatar bound to the Agent session; callers do not pass an avatarUrl. Production is the default API origin. Tests and non-production integrations may pass apiOrigin; the SDK still owns the Agent session route.

Use

Keep the permanent workspace API key on your server. Exchange it for a short-lived Agent session token and give the hook a callback that obtains one for each connection:

import { AvatarStage, useWaffle } from '@animated-waffle/react'

const waffle = useWaffle({
  agentId,
  inputAudioEnabled: false, // Text-triggered, output-only application.
  sessionToken: () => getSessionToken(agentId),
})

return <AvatarStage {...waffle.avatar} style={{ width: 480, height: 480 }} />

The hook returns the app-facing client surface (status, session, transcript, agentSpeaking, error, connect, disconnect, sendText, and the push-to-talk controls) plus the opaque avatar binding for AvatarStage and the avatarLoad projection. Transport audio tracks are not part of this default React API. Its action functions keep stable identity across renders, so effects and event subscriptions can depend on them directly.

AvatarStage owns the renderer lifetime. Session disconnects, reconnects, and replacements only rebind performance signals; they do not remove the visible canvas. Model replacement reuses the stage, so the previous avatar stays visible until the replacement model is ready. The stage is destroyed only when its host component unmounts.

waffle.avatarLoad reports the Agent avatar's loading state:

const label = waffle.avatarLoad.fromCache
  ? 'Loading cached avatar…'
  : waffle.avatarLoad.progress === null
    ? 'Downloading avatar…'
    : `Downloading avatar… ${Math.round(waffle.avatarLoad.progress * 100)}%`

The first VRM download is streamed with byte progress. The SDK verifies the model against the content hash supplied by the Agent session and stores it in browser Cache Storage. Later sessions reuse that content even though their short-lived asset URL is different.

See the SDK documentation for the complete integration guide.