Gestures (Essence 1)

3 steps

1. 1. List the gesture names

   curl -s https://api.bithuman.ai/v1/dynamics/$AGENT_CODE -H "api-secret: $BITHUMAN_API_SECRET"
   # → {"success": true, "data": {"status": "ready", "gestures": {"mini_wave_hello": "…", "clap_cheer": "…"}}}

   The keys of gestures are the names you play, for example mini_wave_hello or clap_cheer.

   Expected

   A JSON body whose gestures object lists your gesture names, such as mini_wave_hello.

   Done: step 1

2. 2. Play one

   Cloud avatar (AvatarSession(avatar_id=…)): send the avatar participant a trigger_dynamics call.

   import json
   
   resp = await ctx.room.local_participant.perform_rpc(
       destination_identity=avatar.avatar_identity,
       method="trigger_dynamics",
       payload=json.dumps({"action": "mini_wave_hello"}),
   )
   # → {"action": "mini_wave_hello", "animation_triggered": true, "status": "success"}

   Self-hosted avatar (AvatarSession(model_path="avatar.imx")): push a VideoControl to the runtime.

   from bithuman import VideoControl
   
   await avatar.runtime.push(VideoControl(action="mini_wave_hello"))

   Expected

   The cloud call returns animation_triggered: true, and the avatar plays the gesture.

   Done: step 2

3. 3. Wire it to your events

   As an allow-listed tool, so the language model can ask for a gesture only from your set. This tool is for a self-hosted avatar (AvatarSession(model_path=…)). For a cloud avatar, put the perform_rpc call from step 2 in the tool body instead.

   from livekit.agents import function_tool, RunContext
   
   ALLOWED = {"mini_wave_hello", "clap_cheer", "thumbs_up_pulse"}
   
   @function_tool()
   async def play_gesture(context: RunContext, gesture: str) -> str:
       if gesture not in ALLOWED:
           return f"Unknown gesture. Options: {sorted(ALLOWED)}"
       await avatar.runtime.push(VideoControl(action=gesture, force_action=True))
       return f"Played {gesture}"

   Other triggers work the same way: a LiveKit data message, a participant event or a timer calls the same line.

   Expected

   Asked for a gesture from your set, the language model calls play_gesture, and the avatar plays it.

   Done: step 3

All steps done.