Merge branch 'main' into fix-openai-conversation-session

Author: seratch

.github/workflows/update-docs.yml

@@ -19,6 +19,7 @@ on:
       - mkdocs.yml
       - '!docs/ja/**'
       - '!docs/ko/**'
+      - '!docs/zh/**'
 
 permissions:
   contents: write

.gitignore

@@ -103,6 +103,7 @@ celerybeat.pid
 .python-version
 .env*
 .venv
+.venv*
 env/
 venv/
 ENV/

docs/context.md

@@ -68,6 +68,51 @@ if __name__ == "__main__":
 4. The context is passed to the `run` function.
 5. The agent correctly calls the tool and gets the age.
 
+---
+
+### Advanced: `ToolContext`
+
+In some cases, you might want to access extra metadata about the tool being executed — such as its name, call ID, or raw argument string.  
+For this, you can use the [`ToolContext`][agents.tool_context.ToolContext] class, which extends `RunContextWrapper`.
+
+```python
+from typing import Annotated
+from pydantic import BaseModel, Field
+from agents import Agent, Runner, function_tool
+from agents.tool_context import ToolContext
+
+class WeatherContext(BaseModel):
+    user_id: str
+
+class Weather(BaseModel):
+    city: str = Field(description="The city name")
+    temperature_range: str = Field(description="The temperature range in Celsius")
+    conditions: str = Field(description="The weather conditions")
+
+@function_tool
+def get_weather(ctx: ToolContext[WeatherContext], city: Annotated[str, "The city to get the weather for"]) -> Weather:
+    print(f"[debug] Tool context: (name: {ctx.tool_name}, call_id: {ctx.tool_call_id}, args: {ctx.tool_arguments})")
+    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")
+
+agent = Agent(
+    name="Weather Agent",
+    instructions="You are a helpful agent that can tell the weather of a given city.",
+    tools=[get_weather],
+)
+```
+
+`ToolContext` provides the same `.context` property as `RunContextWrapper`,  
+plus additional fields specific to the current tool call:
+
+- `tool_name` – the name of the tool being invoked  
+- `tool_call_id` – a unique identifier for this tool call  
+- `tool_arguments` – the raw argument string passed to the tool  
+
+Use `ToolContext` when you need tool-level metadata during execution.  
+For general context sharing between agents and tools, `RunContextWrapper` remains sufficient.
+
+---
+
 ## Agent/LLM context
 
 When an LLM is called, the **only** data it can see is from the conversation history. This means that if you want to make some new data available to the LLM, you must do it in a way that makes it available in that history. There are a few ways to do this:

docs/scripts/translate_docs.py

@@ -27,6 +27,7 @@
 languages = {
     "ja": "Japanese",
     "ko": "Korean",
+    "zh": "Chinese",
     # Add more languages here, e.g., "fr": "French"
 }
 
@@ -114,6 +115,30 @@
         "Build your first agent in minutes.": "단 몇 분 만에 첫 에이전트를 만들 수 있습니다",
         "Let's build": "시작하기",
     },
+    "zh": {
+        "agents": "智能体",
+        "computer use": "计算机操作",
+        "OAI hosted tools": "由OpenAI托管的工具",
+        "well formed data": "格式良好的数据",
+        "guardrail": "安全防护措施",
+        "handoffs": "任务转移",
+        "function tools": "工具调用",
+        "tracing": "追踪",
+        "code examples": "代码示例",
+        "vector store": "向量存储",
+        "deep research": "深度研究",
+        "category": "目录",
+        "user": "用户",
+        "parameter": "参数",
+        "processor": "进程",
+        "server": "服务",
+        "web search": "网络检索",
+        "file search": "文件检索",
+        "streaming": "流式传输",
+        "system prompt": "系统提示词",
+        "Python first": "Python 优先",
+        # Add more mappings here
+    },
     # Add more languages here
 }
 eng_to_non_eng_instructions = {
@@ -136,6 +161,13 @@
         "* 'instructions', 'tools' 같은 API 매개변수와 temperature, top_p, max_tokens, presence_penalty, frequency_penalty 등은 영문 그대로 유지하세요.",
         "* 문장이 아닌 불릿 항목 끝에는 마침표를 찍지 마세요.",
     ],
+    "zh": [
+        "* The term 'examples' must be code examples when the page mentions the code examples in the repo, it can be translated as either 'code examples' or 'sample code'.",
+        "* The term 'primitives' can be translated as basic components.",
+        "* When the terms 'instructions' and 'tools' are mentioned as API parameter names, they must be kept as is.",
+        "* The terms 'temperature', 'top_p', 'max_tokens', 'presence_penalty', 'frequency_penalty' as parameter names must be kept as is.",
+        "* Keep the original structure like `* **The thing**: foo`; this needs to be translated as `* **(translation)**: (translation)`",
+    ],
     # Add more languages here
 }