py-active-call-cc

Python Active-Call: real-time audio streaming with WebSocket and WebRTC.

This repo contains a Python 3.11+ codebase for building low-latency voice pipelines (capture, stream, and process audio) using WebRTC and WebSockets. It is currently in an early, experimental stage.

Usage

启动

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

使用 agent profile（推荐）

python -m app.main --agent-profile default

使用指定 YAML

python -m app.main --agent-config config/agents/default.yaml

Agent 配置路径优先级

1. --agent-config
2. --agent-profile（映射到 config/agents/<profile>.yaml）
3. AGENT_CONFIG_PATH
4. AGENT_PROFILE
5. config/agents/default.yaml（若存在）

说明

• Agent 相关配置是严格模式：YAML 缺少必须项会直接报错，不会回退到 .env 或代码默认值。
• 如果要引用环境变量，请在 YAML 显式写 ${ENV_VAR}。
• siliconflow 独立 section 已移除；请在 agent.llm / agent.tts / agent.asr 内通过 provider、api_key、api_url、model 配置。
• 现在支持在 Agent YAML 中配置 agent.tools（列表），用于声明运行时可调用工具。
• 工具配置示例见 config/agents/tools.yaml。

Backend Integration

Engine runtime now supports adapter-based backend integration:

• BACKEND_MODE=auto|http|disabled
• BACKEND_URL + BACKEND_TIMEOUT_SEC
• HISTORY_ENABLED=true|false

Behavior:

• auto: use HTTP backend only when BACKEND_URL is set, otherwise engine-only mode.
• http: force HTTP backend; falls back to engine-only mode when URL is missing.
• disabled: force engine-only mode (no backend calls).

History write path is now asynchronous and buffered per session:

• HISTORY_QUEUE_MAX_SIZE
• HISTORY_RETRY_MAX_ATTEMPTS
• HISTORY_RETRY_BACKOFF_SEC
• HISTORY_FINALIZE_DRAIN_TIMEOUT_SEC

This keeps turn processing responsive even when backend history APIs are slow/failing.

Detailed notes: docs/backend_integration.md.

测试

python examples/test_websocket.py

python mic_client.py

WS Protocol

/ws uses a strict v1 JSON control protocol with binary PCM audio frames.

See docs/ws_v1_schema.md.