genio-sdk 0.2.1

Connect your AI agent to a Genio avatar — face, voice, and real-time video.

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?)

Param	Type	Required	Description
api_key	str	Yes	Your BYOA API key (starts with gk_)
avatar_id	str	Yes	The avatar document ID
base_url	str	No	Genio API base URL (default: https://genio.works)

@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

Flag / env	Description
--api-key / GENIO_API_KEY	BYOA key
--avatar-id / GENIO_AVATAR_ID	Avatar ID
--base-url / GENIO_BASE_URL	API base (default https://genio.works)
--backend / GENIO_BRIDGE_BACKEND	stub, hermes, or custom
--model / HERMES_GENIO_MODEL	Hermes model
--agent-module / GENIO_AGENT_MODULE	package.module:callable for custom backend