Skip to content

Commit cb1ac74

Browse files
SepineTamSepineTam
committed
docs: Add Chinese docs for release, REPL, and tracing
Added new Chinese documentation files: release.md, repl.md, and tracing.md. Updated usage.md with improved Chinese translation and terminology for usage tracking. These changes enhance the SDK's documentation for Chinese-speaking users.
1 parent dfe86dd commit cb1ac74

File tree

4 files changed

+232
-25
lines changed

4 files changed

+232
-25
lines changed

‎docs/cn/release.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
search:
3+
exclude: true
4+
---
5+
# 发布流程/变更日志
6+
7+
本项目采用稍作修改的语义化版本控制，使用 `0.Y.Z` 形式。开头的 `0` 表示 SDK 仍在快速发展。各组件的增量如下：
8+
9+
## 次要（`Y`）版本
10+
11+
对于未标记为beta的公共接口的**重大更改**，我们将增加次要版本 `Y`。例如，从 `0.0.x` 到 `0.1.x` 的更新可能包含重大更改。
12+
13+
如果你想避免重大更改，我们建议在你的项目中固定到 `0.0.x` 版本。
14+
15+
## 补丁（`Z`）版本
16+
17+
对于非重大更改，我们将递增 `Z`：
18+
19+
- 错误修复
20+
- 新功能
21+
- 私有接口的更改
22+
- beta功能的更新
23+
24+
## 重大更改变更日志
25+
26+
### 0.2.0
27+
28+
在此版本中，一些以前接受 `Agent` 作为参数的地方现在改为接受 `AgentBase` 作为参数。例如，MCP 服务器中的 `list_tools()` 调用。这只是一个类型更改，你仍然可以接收 `Agent` 对象。要更新，只需通过将 `Agent` 替换为 `AgentBase` 来修复类型错误。
29+
30+
### 0.1.0
31+
32+
在此版本中，[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] 添加了两个新参数：`run_context` 和 `agent`。你需要将这些参数添加到任何继承自 `MCPServer` 的类中。

‎docs/cn/repl.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
search:
3+
exclude: true
4+
---
5+
# REPL 实用工具
6+
7+
SDK 提供了 `run_demo_loop`，用于直接在终端中快速、交互式地测试智能体的行为。
8+
9+
10+
```python
11+
import asyncio
12+
from agents import Agent, run_demo_loop
13+
14+
async def main() -> None:
15+
agent = Agent(name="Assistant", instructions="You are a helpful assistant.")
16+
await run_demo_loop(agent)
17+
18+
if __name__ == "__main__":
19+
asyncio.run(main())
20+
```
21+
22+
`run_demo_loop` 会在循环中提示用户输入，并在轮次之间保持对话历史。默认情况下，它会随着生成而流式传输模型输出。当你运行上面的示例时，run_demo_loop 会启动一个交互式聊天会话。它会持续要求你的输入，在轮次之间记住整个对话历史（这样你的智能体就知道讨论了什么），并自动实时地将智能体的响应流式传输给你，就像它们生成时一样。
23+
24+
要结束此聊天会话，只需输入 `quit` 或 `exit`（然后按 Enter）或使用 `Ctrl-D` 键盘快捷键。

‎docs/cn/tracing.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
search:
3+
exclude: true
4+
---
5+
# 追踪功能
6+
7+
Agents SDK包含内置的追踪功能，可全面记录智能体运行期间的事件：LLM生成、工具调用、交接、护栏，甚至发生的自定义事件。使用[追踪仪表板](https://platform.openai.com/traces)，你可以在开发和生产环境中调试、可视化和监控你的工作流程。
8+
9+
!!!note
10+
11+
追踪功能默认启用。有两种方法可以禁用追踪：
12+
13+
1. 你可以通过设置环境变量 `OPENAI_AGENTS_DISABLE_TRACING=1` 来全局禁用追踪
14+
2. 你可以通过将 [`agents.run.RunConfig.tracing_disabled`][] 设置为 `True` 来针对单次运行禁用追踪
15+
16+
***对于使用OpenAI API并在零数据保留(ZDR)策略下运营的组织，追踪功能不可用。***
17+
18+
## 追踪和跨度
19+
20+
- **追踪** 代表"工作流"的单个端到端操作。它们由跨度组成。追踪具有以下属性:
21+
- `workflow_name`: 这是逻辑工作流或应用。例如"代码生成"或"客户服务"。
22+
- `trace_id`: 追踪的唯一ID。如果你没有传递一个，它会自动生成。格式必须是 `trace_<32_字母数字>`。
23+
- `group_id`: 可选的组ID，用于链接来自同一会话的多个追踪。例如，你可以使用聊天线程ID。
24+
- `disabled`: 如果为True，该追踪将不会被记录。
25+
- `metadata`: 追踪的可选元数据。
26+
- **跨度** 代表具有开始和结束时间的操作。跨度具有:
27+
- `started_at` 和 `ended_at` 时间戳。
28+
- `trace_id`，表示它们所属的追踪
29+
- `parent_id`，指向此跨度的父跨度（如果有）
30+
- `span_data`，这是关于跨度的信息。例如，`AgentSpanData` 包含关于智能体的信息，`GenerationSpanData` 包含关于LLM生成的信息等。
31+
32+
## デフォルトのトレーシング
33+
34+
デフォルトでは、 SDK は次をトレースします:
35+
36+
- 全体の `Runner.{run, run_sync, run_streamed}()` は `trace()` でラップされます。
37+
- エージェントが実行されるたびに、`agent_span()` でラップされます
38+
- LLM 生成は `generation_span()` でラップされます
39+
- 関数ツールの呼び出しは個々に `function_span()` でラップされます
40+
- ガードレールは `guardrail_span()` でラップされます
41+
- ハンドオフは `handoff_span()` でラップされます
42+
- 音声入力（音声認識）は `transcription_span()` でラップされます
43+
- 音声出力（音声合成）は `speech_span()` でラップされます
44+
- 関連する音声スパンは `speech_group_span()` の子になる場合があります
45+
46+
デフォルトでは、トレース名は "Agent workflow" です。`trace` を使う場合にこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定することもできます。
47+
48+
さらに、[カスタム トレース プロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先に出力できます（置き換え、または副次的な送信先として）。
49+
50+
## 上位レベルのトレース
51+
52+
`run()` への複数回の呼び出しを 1 つのトレースにまとめたい場合があります。これを行うには、コード全体を `trace()` でラップします。
53+
54+
```python
55+
from agents import Agent, Runner, trace
56+
57+
async def main():
58+
agent = Agent(name="Joke generator", instructions="Tell funny jokes.")
59+
60+
with trace("Joke workflow"): # (1)!
61+
first_result = await Runner.run(agent, "Tell me a joke")
62+
second_result = await Runner.run(agent, f"Rate this joke: {first_result.final_output}")
63+
print(f"Joke: {first_result.final_output}")
64+
print(f"Rating: {second_result.final_output}")
65+
```
66+
67+
1. `Runner.run` への 2 回の呼び出しが `with trace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。
68+
69+
## トレースの作成
70+
71+
[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります:
72+
73+
1. 推奨: トレースをコンテキストマネージャとして使用します（例: `with trace(...) as my_trace`）。これにより、適切なタイミングで自動的に開始・終了します。
74+
2. 手動で [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を呼び出すこともできます。
75+
76+
現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。これは自動的に並行処理で機能することを意味します。トレースを手動で開始/終了する場合、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。
77+
78+
## スパンの作成
79+
80+
各種の [`*_span()`][agents.tracing.create] メソッドを使ってスパンを作成できます。一般的にはスパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するために、[`custom_span()`][agents.tracing.custom_span] 関数を利用できます。
81+
82+
スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡される、最も近い現在のスパンの下にネストされます。
83+
84+
## 機微データ
85+
86+
一部のスパンは機微なデータを取得する可能性があります。
87+
88+
`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらには機微なデータが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってその取得を無効化できます。
89+
90+
同様に、音声スパンはデフォルトで入出力の音声に対して base64 でエンコードされた PCM データを含みます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して、この音声データの取得を無効化できます。
91+
92+
## カスタム トレーシング プロセッサー
93+
94+
トレーシングの高レベルなアーキテクチャは次のとおりです:
95+
96+
- 初期化時に、トレースを作成する役割を持つグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。
97+
- `TraceProvider` に、スパン/トレースをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信する [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定します。`BackendSpanExporter` は OpenAI バックエンドへバッチでエクスポートします。
98+
99+
デフォルト設定をカスタマイズし、別のバックエンドに送る／追加のバックエンドに複製する／エクスポーターの挙動を変更するには、次の 2 つの方法があります:
100+
101+
1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースとスパンの準備が整い次第それらを受け取る、**追加の** トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて、独自の処理を行えます。
102+
2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレースプロセッサーに**置き換え**られます。OpenAI バックエンドにトレースを送るには、その処理を行う `TracingProcessor` を含める必要があります。
103+
104+
## 非 OpenAI モデルでのトレーシング
105+
106+
OpenAI の API キーを非 OpenAI モデルで使用すると、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効化できます。
107+
108+
```python
109+
import os
110+
from agents import set_tracing_export_api_key, Agent, Runner
111+
from agents.extensions.models.litellm_model import LitellmModel
112+
113+
tracing_api_key = os.environ["OPENAI_API_KEY"]
114+
set_tracing_export_api_key(tracing_api_key)
115+
116+
model = LitellmModel(
117+
model="your-model-name",
118+
api_key="your-api-key",
119+
)
120+
121+
agent = Agent(
122+
name="Assistant",
123+
model=model,
124+
)
125+
```
126+
127+
## 注意事項
128+
- 無料のトレースは OpenAI Traces ダッシュボードで表示できます。
129+
130+
## 外部トレーシング プロセッサー一覧
131+
132+
- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents)
133+
- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk)
134+
- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents)
135+
- [MLflow (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
136+
- [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing)
137+
- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk)
138+
- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents)
139+
- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk)
140+
- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration)
141+
- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent)
142+
- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk)
143+
- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk)
144+
- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents)
145+
- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents)
146+
- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk)
147+
- [Okahu-Monocle](https://github.com/monocle2ai/monocle)
148+
- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration)
149+
- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents)
150+
- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk)
151+
- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents)

‎docs/cn/usage.md‎

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,23 @@
22
search:
33
exclude: true
44
---
5-
# 使用状況
5+
# 使用统计
66

7-
Agents SDK は、各実行のトークン使用状況を自動的に追跡します。実行コンテキストから参照でき、コストの監視、制限の適用、分析の記録に利用できます。
7+
Agents SDK会自动跟踪每次运行的token使用情况。你可以从运行上下文中访问它，用于监控成本、强制执行限制或记录分析。
88

9-
## 追跡対象
9+
## 跟踪内容
1010

11-
- **requests**: 実行された LLM API 呼び出し数
12-
- **input_tokens**: 送信された入力トークンの合計
13-
- **output_tokens**: 受信した出力トークンの合計
14-
- **total_tokens**: input + output
11+
- **requests**: 发出的LLM API调用数量
12+
- **input_tokens**: 发送的总输入token数
13+
- **output_tokens**: 接收的总输出token数
14+
- **total_tokens**: 输入 + 输出
1515
- **details**:
1616
- `input_tokens_details.cached_tokens`
1717
- `output_tokens_details.reasoning_tokens`
1818

19-
## 実行からの使用状況の取得
19+
## 从运行中访问使用情况
2020

21-
`Runner.run(...)` の後、`result.context_wrapper.usage` から使用状況にアクセスします。
21+
在 `Runner.run(...)` 之后，通过 `result.context_wrapper.usage` 访问使用情况。
2222

2323
```python
2424
result = await Runner.run(agent, "What's the weather in Tokyo?")
@@ -30,11 +30,11 @@ print("Output tokens:", usage.output_tokens)
3030
print("Total tokens:", usage.total_tokens)
3131
```
3232

33-
使用状況は、実行中のすべてのモデル呼び出し（ツール呼び出しや ハンドオフ を含む）にわたって集計されます。
33+
使用情况在运行期间的所有模型调用（包括工具调用和交接）中进行汇总。
3434

35-
### LiteLLM モデルでの使用状況の有効化
35+
### 启用LiteLLM模型的使用情况
3636

37-
LiteLLM プロバイダーは、デフォルトでは使用状況メトリクスを報告しません。[`LitellmModel`](models/litellm.md) を使用する場合、エージェントに `ModelSettings(include_usage=True)` を渡すことで、LiteLLM のレスポンスが `result.context_wrapper.usage` に反映されます。
37+
LiteLLM提供程序默认不报告使用指标。当你使用 [`LitellmModel`](models/litellm.md) 时，向你的智能体传递 `ModelSettings(include_usage=True)`，这样LiteLLM响应就会填充到 `result.context_wrapper.usage` 中。
3838

3939
```python
4040
from agents import Agent, ModelSettings, Runner
@@ -50,37 +50,37 @@ result = await Runner.run(agent, "What's the weather in Tokyo?")
5050
print(result.context_wrapper.usage.total_tokens)
5151
```
5252

53-
## セッションでの使用状況の取得
53+
## 在会话中获取使用情况
5454

55-
`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その実行に固有の使用状況を返します。セッションはコンテキスト用に会話履歴を保持しますが、各実行の使用状況は独立しています。
55+
当你使用 `Session`（例如 `SQLiteSession`）时，每次调用 `Runner.run(...)` 都会返回该特定运行的使用情况。会话为上下文维护对话历史，但每次运行的使用情况是独立的。
5656

5757
```python
5858
session = SQLiteSession("my_conversation")
5959

6060
first = await Runner.run(agent, "Hi!", session=session)
61-
print(first.context_wrapper.usage.total_tokens) # Usage for first run
61+
print(first.context_wrapper.usage.total_tokens) # 第一次运行的使用情况
6262

6363
second = await Runner.run(agent, "Can you elaborate?", session=session)
64-
print(second.context_wrapper.usage.total_tokens) # Usage for second run
64+
print(second.context_wrapper.usage.total_tokens) # 第二次运行的使用情况
6565
```
6666

67-
セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用状況メトリクスは、その特定の実行のみを表します。セッションでは、前のメッセージが各実行の入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。
67+
请注意，虽然会话在运行之间保留对话上下文，但每次 `Runner.run()` 调用返回的使用情况指标只代表该特定执行。在会话中，先前的消息可能会作为输入重新提供给每次运行，这会影响后续轮次的输入token计数。
6868

69-
## フックでの使用状況の利用
69+
## 在钩子中使用使用情况
7070

71-
`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクルの重要なタイミングで使用状況を記録できます。
71+
如果你正在使用 `RunHooks`，传递给每个钩子的 `context` 对象包含 `usage`。这让你在关键生命周期时刻记录使用情况。
7272

7373
```python
7474
class MyHooks(RunHooks):
7575
async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None:
7676
u = context.usage
77-
print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens")
77+
print(f"{agent.name} → {u.requests} 次请求, {u.total_tokens} 总token数")
7878
```
7979

80-
## API リファレンス
80+
## API 参考
8181

82-
詳細な API ドキュメントは以下をご覧ください。
82+
有关详细的 API 文档，请参见：
8383

84-
- [`Usage`][agents.usage.Usage] - 使用状況の追跡データ構造
85-
- [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用状況へアクセス
86-
- [`RunHooks`][agents.run.RunHooks] - 使用状況追跡のライフサイクルにフックする
84+
- [`Usage`][agents.usage.Usage] - 使用情况跟踪数据结构
85+
- [`RunContextWrapper`][agents.run.RunContextWrapper] - 从运行上下文访问使用情况
86+
- [`RunHooks`][agents.run.RunHooks] - 挂钩到使用情况跟踪生命周期

0 commit comments

Comments
 (0)