genio-sdk

Connect your AI agent to a Genio avatar. Your agent handles the conversation logic; Genio handles the face, voice, and real-time video.

Install

pip install genio-sdk

Quick Start (CLI)

export GENIO_API_KEY="gk_..."
export GENIO_AVATAR_ID="your_avatar_id"

# Test connectivity (placeholder agent)
genio-bridge --backend stub

# Hermes (requires run_agent on PYTHONPATH)
genio-bridge --backend hermes --model "provider/model"

# Custom agent module
export GENIO_AGENT_MODULE="my_agent.bridge:stream_reply"
genio-bridge --backend custom

Create a .env file in your working directory — the CLI loads it automatically via python-dotenv.

You should see SSE connected in the logs; the Genio dashboard shows Agent Connected within a few seconds.

One-click install (macOS / Linux)

curl -sL https://genio.works/bridge.sh | bash -s -- \
  --api-key "gk_..." \
  --avatar-id "your_avatar_id" \
  --backend stub

Library usage

from genio import GenioBridge

bridge = GenioBridge(api_key="gk_xxx", avatar_id="your_avatar_id")

@bridge.on_user_speech
async def handle(text, turn_id, reply):
    async for token in my_agent.stream(text):
        await reply.send_token(token)
    await reply.done()

bridge.run()  # blocks, auto-reconnects

API

GenioBridge(api_key, avatar_id, base_url?)

@bridge.on_user_speech

Decorator to register the handler. The handler receives:

• text — transcribed user speech
• turn_id — unique ID for this conversation turn
• reply — object with:
  • send_token(token) to stream final answer tokens
  • send_status(content) to report progress while your agent is still working
  • done() to end the turn

StatusConfig / run_with_status_updates

For long-running agents, use run_with_status_updates to send periodic status heartbeats while your worker streams tokens (see genio.backends.hermes).

bridge.run() / await bridge.disconnect()

run() blocks and auto-reconnects. disconnect() stops the bridge.

CLI reference