Fishjam Python 服务器 SDK 是面向 Fishjam 平台的服务端 Python 库，安装后以 fishjam 模块导入，PyPI 包名为 fishjam-server-sdk。它用于编写后端逻辑：创建房间、签发 peer 令牌、订阅服务器事件以及运行服务端语音智能体。
使用前建议先阅读平台层的 SKILL.md，其中定义了房间、peer、track、二级令牌模型，以及 WebSocket 与 webhook 两种事件接收方式的取舍，Python SDK 正是建立在这些概念之上。
安装方式支持 pip install fishjam-server-sdk，也可使用 uv add fishjam-server-sdk 或 poetry add fishjam-server-sdk。最小流程为：使用 FishjamClient 传入 fishjam_id 与 management_token 初始化客户端（建议从环境变量读取），调用 create_room() 创建房间，再调用 create_peer(room.id, PeerOptions(metadata={'userId': 'user-123'})) 创建 peer 并获得 peer_token，将 peer_token 下发给客户端使用。
主要组件分为四部分。FishjamClient 是同步客户端，负责 REST 操作，覆盖房间、peer、智能体、直播/MoQ 令牌以及订阅模式。FishjamNotifier 是异步客户端，基于 asyncio 与 websockets 建立持久 WebSocket 连接，通过 @notifier.on_server_notification 装饰器注册处理函数以接收所有事件。receive_binary(bytes) 为同步方法，用于将 HTTP webhook 请求体解码为类型化事件。Agent 与 AgentSession 为异步接口，用于构建服务端语音智能体，支持对传入消息做异步迭代，并通过 await track.send_chunk(...) 发送音频分片。
架构上有一点与 JS SDK 不同：FishjamClient 是同步的，create_room、create_peer、delete_peer 等方法是普通 def 而非 async def。可以在同步路由中直接调用；若处于异步上下文，可通过 run_in_executor 调用，或在热路径中使用 await asyncio.to_thread(fishjam_client.create_peer, ...)。FishjamNotifier 与 Agent 则为异步，Agent 使用 async with agent.connect() as session: 作为唯一入口。receive_binary 是同步方法，可在一个异步 FastAPI 路由中直接调用 receive_binary(await req.body())。
关键规则方面：需要 Python 3.10+，SDK 使用了 match、结构化类型与 PEP 604 联合类型。FishjamNotifier 不会自动重连，其 connect() 协程会一直运行到 WebSocket 关闭，因此需要用监管循环包裹。每个 notifier 只允许一个处理函数，@notifier.on_server_notification 只会保存最后一次装饰的函数，如需分派多类事件，应在这唯一的处理函数中用 match 按消息类型区分。处理函数可以是同步或异步，可通过 inspect.isawaitable(result) 判断是否需要 await。管理令牌必须保留在服务器端，不得泄漏。
参考资料按任务划分：查询 FishjamClient 全部方法、数据类与错误类型见 client.md；FishjamNotifier、wait_ready、装饰器模式与事件类型模式匹配见 notifier.md；receive_binary、FastAPI/Flask 接收器与安全模式见 webhooks.md；Agent、AgentSession、OutgoingAudioTrackOptions 与 receive() 异步迭代器见 agent.md；接入 Gemini Live 见 gemini-integration.md（fishjam.integrations.gemini 与 GeminiIntegration 单例）；FastAPI 与 Flask 接线模式见 fastapi.md；签发直播/MoQ 令牌见 livestream-and-moq.md（create_livestream_streamer_token、create_livestream_viewer_token、create_moq_token）；手动订阅模式见 selective-subscriptions.md（subscribe_peer / subscribe_tracks 配合 subscribe_mode='manual' 的房间）。
适用场景包括：需要 Python 后端管理 Fishjam 房间与 peer 令牌的服务、通过 WebSocket 或 webhook 接收服务端事件的后台服务、以及用 Python 构建服务端语音智能体并将其接入 Gemini Live 等场景。限制方面：仅支持服务端使用，管理令牌不可下发到客户端；要求 Python 3.10+；notifier 不自动重连，需自行实现重连逻辑；每个 notifier 只能设一个事件处理函数。具体收费、价格与配额信息在资料中暂未提供。