chore: import upstream snapshot with attribution

2026-07-13 12:39:17 +08:00
commit 4ed4e9ff99
1368 changed files with 334957 additions and 0 deletions
@@ -0,0 +1,348 @@
+---
+search:
+  exclude: true
+---
+# 实时智能体指南
+
+本指南说明OpenAI Agents SDK的实时层如何映射到OpenAI Realtime API，以及 Python SDK 在其之上添加了哪些额外行为。
+
+!!! note "从这里开始"
+
+    如果你想使用默认的 Python 路径，请先阅读[快速入门](quickstart.md)。如果你正在决定应用应使用服务端 WebSocket 还是 SIP，请阅读[实时传输](transport.md)。浏览器 WebRTC 传输不属于 Python SDK。
+
+## 概览
+
+实时智能体会与Realtime API保持一个长连接，以便模型可以增量处理文本和音频、流式传输音频输出、调用工具，并处理中断，而无需在每一轮都重新发起请求。
+
+主要 SDK 组件包括：
+
+-   **RealtimeAgent**：一个实时专家智能体的 instructions、tools、输出安全防护措施和任务转移
+-   **RealtimeRunner**：会话工厂，用于将起始智能体连接到实时传输
+-   **RealtimeSession**：实时会话，用于发送输入、接收事件、跟踪历史记录并执行工具
+-   **RealtimeModel**：传输抽象层。默认使用OpenAI的服务端 WebSocket 实现。
+
+## 会话生命周期
+
+典型的实时会话如下：
+
+1. 创建一个或多个 `RealtimeAgent`。
+2. 使用起始智能体创建一个 `RealtimeRunner`。
+3. 调用 `await runner.run()` 获取一个 `RealtimeSession`。
+4. 使用 `async with session:` 或 `await session.enter()` 进入会话。
+5. 使用 `send_message()` 或 `send_audio()` 发送用户输入。
+6. 迭代会话事件，直到对话结束。
+
+与纯文本运行不同，`runner.run()` 不会立即生成最终结果。它会返回一个实时会话对象，该对象会将本地历史记录、后台工具执行、安全防护措施状态以及活动智能体配置与传输层保持同步。
+
+默认情况下，`RealtimeRunner` 使用 `OpenAIRealtimeWebSocketModel`，因此默认的 Python 路径是到Realtime API的服务端 WebSocket 连接。如果你传入不同的 `RealtimeModel`，相同的会话生命周期和智能体功能仍然适用，而连接机制可以发生变化。
+
+## 智能体和会话配置
+
+`RealtimeAgent` 的范围有意比常规 `Agent` 类型更窄：
+
+-   模型选择在会话层级配置，而不是按智能体配置。
+-   不支持structured outputs。
+-   可以配置音色，但在会话已经生成过语音音频后就不能再更改。
+-   instructions、工具调用、任务转移、钩子和输出安全防护措施仍然都可用。
+
+`RealtimeSessionModelSettings` 同时支持较新的嵌套式 `audio` 配置和较旧的扁平别名。新代码建议优先使用嵌套形式，并为新的实时智能体从 `gpt-realtime-2.1` 开始：
+
+```python
+runner = RealtimeRunner(
+    starting_agent=agent,
+    config={
+        "model_settings": {
+            "model_name": "gpt-realtime-2.1",
+            "audio": {
+                "input": {
+                    "format": "pcm16",
+                    "transcription": {"model": "gpt-4o-mini-transcribe"},
+                    "turn_detection": {"type": "semantic_vad", "interrupt_response": True},
+                },
+                "output": {"format": "pcm16", "voice": "ash"},
+            },
+            "tool_choice": "auto",
+        }
+    },
+)
+```
+
+有用的会话级设置包括：
+
+-   `audio.input.format`、`audio.output.format`
+-   `audio.input.transcription`
+-   `audio.input.noise_reduction`
+-   `audio.input.turn_detection`
+-   `audio.output.voice`、`audio.output.speed`
+-   `output_modalities`
+-   `tool_choice`
+-   `prompt`
+-   `tracing`
+
+`RealtimeRunner(config=...)` 上有用的运行级设置包括：
+
+-   `async_tool_calls`
+-   `output_guardrails`
+-   `guardrails_settings.debounce_text_length`
+-   `tool_error_formatter`
+-   `tracing_disabled`
+
+有关完整的类型化接口，请参阅 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 和 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]。
+
+## 输入与输出
+
+### 文本和结构化用户消息
+
+使用 [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] 发送纯文本或结构化实时消息。
+
+```python
+from agents.realtime import RealtimeUserInputMessage
+
+await session.send_message("Summarize what we discussed so far.")
+
+message: RealtimeUserInputMessage = {
+    "type": "message",
+    "role": "user",
+    "content": [
+        {"type": "input_text", "text": "Describe this image."},
+        {"type": "input_image", "image_url": image_data_url, "detail": "high"},
+    ],
+}
+await session.send_message(message)
+```
+
+结构化消息是在实时对话中包含图像输入的主要方式。[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) 中的示例 Web 演示就是以这种方式转发 `input_image` 消息。
+
+### 音频输入
+
+使用 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio] 流式传输原始音频字节：
+
+```python
+await session.send_audio(audio_bytes)
+```
+
+如果禁用了服务端轮次检测，你需要自行标记轮次边界。高层便捷方法是：
+
+```python
+await session.send_audio(audio_bytes, commit=True)
+```
+
+如果需要更低层级的控制，也可以通过底层模型传输发送原始客户端事件，例如 `input_audio_buffer.commit`。
+
+### 手动响应控制
+
+`session.send_message()` 使用高层路径发送用户输入，并为你启动响应。原始音频缓冲并**不会**在所有配置中自动执行同样操作。
+
+在Realtime API层面，手动轮次控制意味着用原始 `session.update` 清除 `turn_detection`，然后自行发送 `input_audio_buffer.commit` 和 `response.create`。
+
+如果你正在手动管理轮次，可以通过模型传输发送原始客户端事件：
+
+```python
+from agents.realtime.model_inputs import RealtimeModelSendRawMessage
+
+await session.model.send_event(
+    RealtimeModelSendRawMessage(
+        message={
+            "type": "response.create",
+        }
+    )
+)
+```
+
+此模式适用于以下场景：
+
+-   `turn_detection` 已禁用，并且你想自行决定模型应在何时响应
+-   你想在触发响应之前检查用户输入或对其进行门控
+-   你需要为带外响应使用自定义提示词
+
+[`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) 中的 SIP 示例使用原始 `response.create` 来强制发送开场问候。
+
+## 事件、历史记录和中断
+
+`RealtimeSession` 会发出更高层级的 SDK 事件，同时在需要时仍会转发原始模型事件。
+
+重要的会话事件包括：
+
+-   `audio`、`audio_end`、`audio_interrupted`
+-   `agent_start`、`agent_end`
+-   `tool_start`、`tool_end`、`tool_approval_required`
+-   `handoff`
+-   `history_added`、`history_updated`
+-   `guardrail_tripped`
+-   `input_audio_timeout_triggered`
+-   `error`
+-   `raw_model_event`
+
+对 UI 状态最有用的事件通常是 `history_added` 和 `history_updated`。它们会以 `RealtimeItem` 对象形式公开会话的本地历史记录，包括用户消息、助手消息和工具调用。
+
+### 中断和播放跟踪
+
+当用户打断助手时，会话会发出 `audio_interrupted` 并更新历史记录，使服务端对话与用户实际听到的内容保持一致。
+
+在低延迟本地播放中，默认播放跟踪器通常已经足够。在远程或延迟播放场景中，尤其是电话通信，请使用 [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker]，以便中断截断基于实际播放进度，而不是假设所有已生成音频都已经被听到。
+
+[`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py) 中的 Twilio 示例展示了此模式。
+
+## 工具、审批、任务转移和安全防护措施
+
+### 工具调用
+
+实时智能体支持在实时对话期间使用工具调用：
+
+```python
+from agents import function_tool
+
+
+@function_tool
+def get_weather(city: str) -> str:
+    """Get current weather for a city."""
+    return f"The weather in {city} is sunny, 72F."
+
+
+agent = RealtimeAgent(
+    name="Assistant",
+    instructions="You can answer weather questions.",
+    tools=[get_weather],
+)
+```
+
+### 工具审批
+
+工具调用可以要求在执行前获得人工审批。发生这种情况时，会话会发出 `tool_approval_required`，并暂停工具运行，直到你调用 `approve_tool_call()` 或 `reject_tool_call()`。
+
+如果该工具还具有输入安全防护措施，这些安全防护措施会在审批通过后、执行前立即运行。若要在发出审批事件之前运行它们，请使用 `RealtimeRunner(..., config={"tool_execution": {"pre_approval_tool_input_guardrails": True}})` 创建 runner。通过此预审批检查的调用，在审批后、执行前仍会再次检查。
+
+```python
+async for event in session:
+    if event.type == "tool_approval_required":
+        await session.approve_tool_call(event.call_id)
+```
+
+有关具体的服务端审批循环，请参阅 [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)。人在环路文档也会在[人在环路](../human_in_the_loop.md)中回指此流程。
+
+### 任务转移
+
+实时任务转移让一个智能体可以将实时对话转移给另一位专家：
+
+```python
+from agents.realtime import RealtimeAgent, realtime_handoff
+
+billing_agent = RealtimeAgent(
+    name="Billing Support",
+    instructions="You specialize in billing issues.",
+)
+
+main_agent = RealtimeAgent(
+    name="Customer Service",
+    instructions="Triage the request and hand off when needed.",
+    handoffs=[
+        realtime_handoff(
+            billing_agent,
+            tool_description_override="Transfer to billing support",
+        )
+    ],
+)
+```
+
+裸 `RealtimeAgent` 任务转移会被自动包装，而 `realtime_handoff(...)` 可用于自定义名称、描述、验证、回调和可用性。实时任务转移不支持常规任务转移的 `input_filter`。
+
+### 安全防护措施
+
+实时智能体支持针对智能体响应的输出安全防护措施，以及针对工具调用的输入安全防护措施。输出安全防护措施在经过防抖的转写累积文本上运行，而不是在每个部分 token 上运行，并且它们会发出 `guardrail_tripped`，而不是抛出异常。
+
+```python
+from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail
+
+
+def sensitive_data_check(context, agent, output):
+    return GuardrailFunctionOutput(
+        tripwire_triggered="password" in output,
+        output_info=None,
+    )
+
+
+agent = RealtimeAgent(
+    name="Assistant",
+    instructions="...",
+    output_guardrails=[OutputGuardrail(guardrail_function=sensitive_data_check)],
+)
+```
+
+当实时输出安全防护措施触发时，会话会中断活动响应，强制执行 `response.cancel`，发出 `guardrail_tripped`，并发送一条后续用户消息，指明被触发的安全防护措施，以便模型生成替代响应。你的音频播放器仍应监听 `audio_interrupted` 并立即停止本地播放，因为安全防护措施是在经过防抖的转写文本上运行的，触发条件触发时可能已有部分音频被缓冲。
+
+## SIP 和电话通信
+
+Python SDK 通过 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel] 提供一等的 SIP 附加流程。
+
+当呼叫通过 Realtime Calls API 到达，并且你想将智能体会话附加到生成的 `call_id` 时，请使用它：
+
+```python
+from agents.realtime import RealtimeRunner
+from agents.realtime.openai_realtime import OpenAIRealtimeSIPModel
+
+runner = RealtimeRunner(starting_agent=agent, model=OpenAIRealtimeSIPModel())
+
+async with await runner.run(
+    model_config={
+        "call_id": call_id_from_webhook,
+    }
+) as session:
+    async for event in session:
+        ...
+```
+
+如果你需要先接受呼叫，并希望接受载荷与从智能体派生出的会话配置相匹配，请使用 `OpenAIRealtimeSIPModel.build_initial_session_payload(...)`。完整流程展示在 [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) 中。
+
+## 低层访问和自定义端点
+
+你可以通过 `session.model` 访问底层传输对象。
+
+在以下情况下使用它：
+
+-   通过 `session.model.add_listener(...)` 使用自定义监听器
+-   使用原始客户端事件，例如 `response.create` 或 `session.update`
+-   通过 `model_config` 处理自定义 `url`、`headers` 或 `api_key`
+-   将 `call_id` 附加到现有实时通话
+
+`RealtimeModelConfig` 支持：
+
+-   `api_key`
+-   `url`
+-   `headers`
+-   `initial_model_settings`
+-   `playback_tracker`
+-   `call_id`
+
+本仓库随附的 `call_id` 示例是 SIP。更广泛的Realtime API也会在某些服务端控制流中使用 `call_id`，但这里没有将这些流程打包为 Python 代码示例。
+
+连接到Azure OpenAI时，请传入 GA Realtime 端点 URL 和显式 headers。例如：
+
+```python
+session = await runner.run(
+    model_config={
+        "url": "wss://<your-resource>.openai.azure.com/openai/v1/realtime?model=<deployment-name>",
+        "headers": {"api-key": "<your-azure-api-key>"},
+    }
+)
+```
+
+对于基于 token 的身份验证，请在 `headers` 中使用 bearer token：
+
+```python
+session = await runner.run(
+    model_config={
+        "url": "wss://<your-resource>.openai.azure.com/openai/v1/realtime?model=<deployment-name>",
+        "headers": {"authorization": f"Bearer {token}"},
+    }
+)
+```
+
+如果传入 `headers`，SDK 不会自动添加 `Authorization`。在实时智能体中避免使用旧版 beta 路径（`/openai/realtime?api-version=...`）。
+
+## 更多阅读
+
+-   [实时传输](transport.md)
+-   [快速入门](quickstart.md)
+-   [OpenAI Realtime 对话](https://developers.openai.com/api/docs/guides/realtime-conversations/)
+-   [OpenAI Realtime 服务端控制](https://developers.openai.com/api/docs/guides/realtime-server-controls/)
+-   [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)
@@ -0,0 +1,158 @@
+---
+search:
+  exclude: true
+---
+# 快速入门
+
+Python SDK 中的实时智能体是基于 WebSocket 传输之上的 OpenAI Realtime API 构建的服务端低延迟智能体。
+
+!!! note "Python SDK 边界"
+
+    Python SDK **不**提供浏览器 WebRTC 传输。本页仅介绍由 Python 管理、通过服务端 WebSocket 进行的实时会话。使用此 SDK 进行服务端编排、工具、审批以及电话集成。另请参阅[实时传输](transport.md)。
+
+## 前提条件
+
+-   Python 3.10 或更高版本
+-   OpenAI API 密钥
+-   对 OpenAI Agents SDK 有基本了解
+
+## 安装
+
+如果尚未安装，请安装 OpenAI Agents SDK：
+
+```bash
+pip install openai-agents
+```
+
+## 服务端实时会话创建
+
+### 1. 实时组件导入
+
+```python
+import asyncio
+
+from agents.realtime import RealtimeAgent, RealtimeRunner
+```
+
+### 2. 起始智能体定义
+
+```python
+agent = RealtimeAgent(
+    name="Assistant",
+    instructions="You are a helpful voice assistant. Keep responses short and conversational.",
+)
+```
+
+### 3. runner 配置
+
+对于新代码，优先使用嵌套的 `audio.input` / `audio.output` 会话设置结构。对于新的实时智能体，请从 `gpt-realtime-2.1` 开始。
+
+```python
+runner = RealtimeRunner(
+    starting_agent=agent,
+    config={
+        "model_settings": {
+            "model_name": "gpt-realtime-2.1",
+            "audio": {
+                "input": {
+                    "format": "pcm16",
+                    "transcription": {"model": "gpt-4o-mini-transcribe"},
+                    "turn_detection": {
+                        "type": "semantic_vad",
+                        "interrupt_response": True,
+                    },
+                },
+                "output": {
+                    "format": "pcm16",
+                    "voice": "ash",
+                },
+            },
+        }
+    },
+)
+```
+
+### 4. 会话启动与输入发送
+
+`runner.run()` 返回一个 `RealtimeSession`。当你进入会话上下文时，连接会被打开。
+
+```python
+async def main() -> None:
+    session = await runner.run()
+
+    async with session:
+        await session.send_message("Say hello in one short sentence.")
+
+        async for event in session:
+            if event.type == "audio":
+                # Forward or play event.audio.data.
+                pass
+            elif event.type == "history_added":
+                print(event.item)
+            elif event.type == "agent_end":
+                # One assistant turn finished.
+                break
+            elif event.type == "error":
+                print(f"Error: {event.error}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+`session.send_message()` 接受纯字符串或结构化实时消息。对于原始音频块，请使用 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio]。
+
+## 本快速入门未包含的内容
+
+-   麦克风采集和扬声器播放代码。请参阅 [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) 中的实时代码示例。
+-   SIP / 电话附加流程。请参阅[实时传输](transport.md)和 [SIP 部分](guide.md#sip-and-telephony)。
+
+## 关键设置
+
+基本会话运行后，大多数人接下来会用到的设置包括：
+
+-   `model_name`
+-   `audio.input.format`、`audio.output.format`
+-   `audio.input.transcription`
+-   `audio.input.noise_reduction`
+-   `audio.input.turn_detection` 用于自动轮次检测
+-   `audio.output.voice`
+-   `tool_choice`、`prompt`、`tracing`
+-   `async_tool_calls`、`tool_execution.pre_approval_tool_input_guardrails`、`guardrails_settings.debounce_text_length`、`tool_error_formatter`
+
+较旧的扁平别名（如 `input_audio_format`、`output_audio_format`、`input_audio_transcription` 和 `turn_detection`）仍然可用，但新代码首选嵌套的 `audio` 设置。
+
+对于手动轮次控制，请使用原始的 `session.update` / `input_audio_buffer.commit` / `response.create` 流程，具体如[实时智能体指南](guide.md#manual-response-control)中所述。
+
+完整模式请参阅 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 和 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]。
+
+## 连接选项
+
+在环境中设置你的 API 密钥：
+
+```bash
+export OPENAI_API_KEY="your-api-key-here"
+```
+
+或在启动会话时直接传入：
+
+```python
+session = await runner.run(model_config={"api_key": "your-api-key"})
+```
+
+`model_config` 还支持：
+
+-   `url`：自定义 WebSocket 端点
+-   `headers`：自定义请求头
+-   `call_id`：附加到现有实时通话。在此仓库中，已记录的附加流程是 SIP。
+-   `playback_tracker`：报告用户实际听到的音频量
+
+如果你显式传入 `headers`，SDK 将**不会**为你注入 `Authorization` 标头。
+
+连接到 Azure OpenAI 时，请在 `model_config["url"]` 中传入 GA Realtime 端点 URL，并显式传入 headers。对于实时智能体，请避免使用旧版 beta 路径（`/openai/realtime?api-version=...`）。详情请参阅[实时智能体指南](guide.md#low-level-access-and-custom-endpoints)。
+
+## 后续步骤
+
+-   阅读[实时传输](transport.md)，以在服务端 WebSocket 和 SIP 之间做出选择。
+-   阅读[实时智能体指南](guide.md)，了解生命周期、结构化输入、审批、任务转移、安全防护措施和底层控制。
+-   浏览 [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) 中的代码示例。
@@ -0,0 +1,76 @@
+---
+search:
+  exclude: true
+---
+# 实时传输
+
+使用本页判断实时智能体如何适配你的 Python 应用程序。
+
+!!! note "Python SDK 边界"
+
+    Python SDK **不**包含浏览器 WebRTC 传输。本页仅讨论 Python SDK 的传输选择：服务端 WebSocket 和 SIP 接入流程。浏览器 WebRTC 是一个单独的平台主题，记录在官方 [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 指南中。
+
+## 决策指南
+
+| 目标 | 从这里开始 | 原因 |
+| --- | --- | --- |
+| 构建由服务端管理的实时应用 | [快速入门](quickstart.md) | 默认的 Python 路径是由 `RealtimeRunner` 管理的服务端 WebSocket 会话。 |
+| 了解应选择哪种传输和部署形态 | 本页 | 在确定传输或部署形态之前使用本页。 |
+| 将智能体接入电话或 SIP 通话 | [实时指南](guide.md) 和 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | 该仓库提供了由 `call_id` 驱动的 SIP 接入流程。 |
+
+## 默认 Python 路径：服务端 WebSocket
+
+除非你传入自定义 `RealtimeModel`，否则 `RealtimeRunner` 会使用 `OpenAIRealtimeWebSocketModel`。
+
+这意味着标准 Python 拓扑如下：
+
+1. 你的 Python 服务创建一个 `RealtimeRunner`。
+2. `await runner.run()` 返回一个 `RealtimeSession`。
+3. 进入会话并发送文本、结构化消息或音频。
+4. 消费 `RealtimeSessionEvent` 项，并将音频或转录文本转发到你的应用程序。
+
+这是核心演示应用、CLI 示例和 Twilio Media Streams 示例所使用的拓扑：
+
+-   [`examples/realtime/app`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app)
+-   [`examples/realtime/cli`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/cli)
+-   [`examples/realtime/twilio`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio)
+
+当你的服务负责音频管道、工具执行、审批流程和历史记录处理时，请使用此路径。
+
+## 电话路径：SIP 接入
+
+对于此仓库中记录的电话流程，Python SDK 会通过 `call_id` 接入现有的实时通话。
+
+该拓扑如下：
+
+1. OpenAI 向你的服务发送一个 webhook，例如 `realtime.call.incoming`。
+2. 你的服务通过 Realtime Calls API 接受该通话。
+3. 你的 Python 服务启动一个 `RealtimeRunner(..., model=OpenAIRealtimeSIPModel())`。
+4. 会话使用 `model_config={"call_id": ...}` 连接，然后像任何其他实时会话一样处理事件。
+
+这是 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) 中展示的拓扑。
+
+更广泛的 Realtime API 也会在一些服务端控制模式中使用 `call_id`，但此仓库提供的接入示例是 SIP。
+
+## 本 SDK 范围之外的浏览器 WebRTC
+
+如果你的应用的主要客户端是使用 Realtime WebRTC 的浏览器：
+
+-   将其视为不在此仓库的 Python SDK 文档范围内。
+-   使用官方 [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 和 [实时对话](https://developers.openai.com/api/docs/guides/realtime-conversations/)文档，了解客户端流程和事件模型。
+-   如果你需要在浏览器 WebRTC 客户端之上使用旁路服务端连接，请使用官方 [Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/) 指南。
+-   不要期望此仓库提供浏览器端 `RTCPeerConnection` 抽象或现成的浏览器 WebRTC 示例。
+
+此仓库目前也未提供浏览器 WebRTC 加 Python 旁路服务端示例。
+
+## 自定义端点和接入点
+
+[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig] 中的传输配置界面允许你调整默认路径：
+
+-   `url`：覆盖 WebSocket 端点
+-   `headers`：提供显式标头，例如 Azure 身份验证标头
+-   `api_key`：直接传入 API key，或通过回调传入
+-   `call_id`：接入现有实时通话。在此仓库中，记录的示例是 SIP。
+-   `playback_tracker`：报告实际播放进度，以便处理中断
+
+选择拓扑后，请参阅[实时智能体指南](guide.md)，了解详细生命周期和能力界面。