Skip to content

Commit 21de7d6

Browse files
ischanxischanx
committed
docs(zh): translate docs
1 parent 0a89050 commit 21de7d6

25 files changed

+2243
-0
lines changed

‎docs/src/content/docs/zh/extensions/ai-sdk.mdx‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: 使用任何模型与 Vercel 的 AI SDK
3+
description: Connect your Agents SDK agents to any model through the Vercel's AI SDK
4+
---
5+
6+
import { Aside, Steps, Code } from '@astrojs/starlight/components';
7+
import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw';
8+
9+
<Aside type="caution">
10+
该适配器仍处于测试阶段。您在使用某些模型提供方时可能会遇到问题，尤其是较小的提供方。请通过
11+
[GitHub issues](https://github.com/openai/openai-agents-js/issues)
12+
报告任何问题，我们会尽快修复。
13+
</Aside>
14+
15+
开箱即用，Agents SDK 可通过 Responses API 或 Chat Completions API 与 OpenAI 模型配合使用。不过，如果您希望使用其他模型，[Vercel 的 AI SDK](https://sdk.vercel.ai/) 提供了多种受支持的模型，可通过此适配器接入 Agents SDK。
16+
17+
## 设置
18+
19+
<Steps>
20+
21+
1. 通过安装扩展包来安装 AI SDK 适配器：
22+
23+
```bash
24+
npm install @openai/agents-extensions
25+
```
26+
27+
2. 从 [Vercel 的 AI SDK](https://ai-sdk.dev/docs/foundations/providers-and-models) 选择所需的模型包并进行安装：
28+
29+
```bash
30+
npm install @ai-sdk/openai
31+
```
32+
33+
3. 导入适配器和模型以连接到您的智能体：
34+
35+
```typescript
36+
import { openai } from '@ai-sdk/openai';
37+
import { aisdk } from '@openai/agents-extensions';
38+
```
39+
40+
4. 初始化模型实例，供该智能体使用：
41+
42+
```typescript
43+
const model = aisdk(openai('o4-mini'));
44+
```
45+
46+
</Steps>
47+
48+
<Aside type="caution">
49+
我们目前支持 ai-sdk 的模型提供方的 v2 模块，与 Vercel AI SDK v5
50+
兼容。如果您有特定原因需要继续使用 v1 模型提供方，可以从
51+
[examples/ai-sdk-v1](https://github.com/openai/openai-agents-js/tree/main/examples/ai-sdk-v1)
52+
复制该模块并将其包含到您的项目中。
53+
</Aside>
54+
55+
## 示例
56+
57+
<Code lang="typescript" code={aiSdkSetupExample} title="AI SDK 设置" />
58+
59+
## 提供方元数据传递
60+
61+
如果您需要随消息发送提供方特定的选项，请通过 `providerMetadata` 传递。这些值会直接转发给底层的 AI SDK 模型。例如，在 Agents SDK 中如下的 `providerData`
62+
63+
```ts
64+
providerData: {
65+
anthropic: {
66+
cacheControl: {
67+
type: 'ephemeral';
68+
}
69+
}
70+
}
71+
```
72+
73+
将会变为
74+
75+
```ts
76+
providerMetadata: {
77+
anthropic: {
78+
cacheControl: {
79+
type: 'ephemeral';
80+
}
81+
}
82+
}
83+
```
84+
85+
在使用 AI SDK 集成时。

‎docs/src/content/docs/zh/extensions/twilio.mdx‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: 使用实时智能体与 Twilio
3+
description: Connect your Agents SDK agents to Twilio to use voice agents
4+
---
5+
6+
import { Aside, Steps, Code } from '@astrojs/starlight/components';
7+
import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw';
8+
import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw';
9+
10+
Twilio 提供一个 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)，可将电话通话中的原始音频发送到 WebSocket 服务器。此设置可用于将您的 [Overview](/openai-agents-js/zh/guides/voice-agents) 连接到 Twilio。您可以使用 `websocket` 模式下的默认 Realtime Session 传输，将来自 Twilio 的事件连接到您的 Realtime Session。不过，这需要您设置正确的音频格式，并调整自己的打断时机，因为与基于 Web 的对话相比，电话通话自然会引入更高的延迟。
11+
12+
为提升搭建体验，我们创建了专用的传输层，替您处理与 Twilio 的连接，包括处理打断和音频转发。
13+
14+
<Aside type="caution">
15+
该适配器仍处于测试阶段。您可能会遇到极端情况的问题或 Bug。 请通过 [GitHub
16+
issues](https://github.com/openai/openai-agents-js/issues)
17+
报告任何问题，我们会尽快修复。
18+
</Aside>
19+
20+
## 设置
21+
22+
<Steps>
23+
24+
1. **请确保您拥有 Twilio 账号和一个 Twilio 电话号码。**
25+
26+
2. **设置一个可以接收来自 Twilio 事件的 WebSocket 服务器。**
27+
28+
如果您在本地开发，这将需要您配置一个本地隧道，比如
29+
这将需要您配置一个本地隧道，比如 [`ngrok`](https://ngrok.io/) 或
30+
[Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/)
31+
以便让 Twilio 访问您的本地服务器。您可以使用 `TwilioRealtimeTransportLayer`
32+
来连接到 Twilio。
33+
34+
3. **通过安装扩展包来安装 Twilio 适配器：**
35+
36+
```bash
37+
npm install @openai/agents-extensions
38+
```
39+
40+
4. **导入适配器和模型以连接到您的 `RealtimeSession`：**
41+
42+
<Code
43+
lang="typescript"
44+
code={twilioBasicExample.replace(
45+
/\n\s+\/\/ @ts-expect-error - this is not defined/g,
46+
'',
47+
)}
48+
/>
49+
50+
5. **将您的 `RealtimeSession` 连接到 Twilio：**
51+
52+
```typescript
53+
session.connect({ apiKey: 'your-openai-api-key' });
54+
```
55+
56+
</Steps>
57+
58+
任何您期望从 `RealtimeSession` 获得的事件和行为都会按预期工作，包括工具调用、护栏等。阅读 [Overview](/openai-agents-js/zh/guides/voice-agents) 以了解如何将 `RealtimeSession` 与语音智能体一起使用的更多信息。
59+
60+
## 提示与注意事项
61+
62+
1. **速度是关键。**
63+
64+
为了接收来自 Twilio 的所有必要事件和音频，一旦您拿到 WebSocket 连接的引用，就应尽快创建
65+
`TwilioRealtimeTransportLayer` 实例，并立即调用 `session.connect()`。
66+
67+
2. **访问 Twilio 的原始事件。**
68+
69+
如果您想访问 Twilio 发送的原始事件，可以在 `RealtimeSession` 实例上监听
70+
`transport_event` 事件。来自 Twilio 的每个事件的 `type` 都是 `twilio_message`，并包含一个 `message` 属性，其中包含原始事件数据。
71+
72+
3. **查看调试日志。**
73+
74+
有时您可能会遇到需要更多信息才能定位的问题。使用 `DEBUG=openai-agents*` 环境变量将显示来自 Agents SDK 的所有调试日志。或者，您也可以仅为 Twilio 适配器启用调试日志：
75+
`DEBUG=openai-agents:extensions:twilio*`。
76+
77+
## 完整示例服务器
78+
79+
下面是一个端到端的 WebSocket 服务器示例，它接收来自 Twilio 的请求并将其转发到 `RealtimeSession`。
80+
81+
<Code
82+
lang="typescript"
83+
code={twilioServerExample}
84+
title="使用 Fastify 的示例服务器"
85+
/>

‎docs/src/content/docs/zh/guides/agents.mdx‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: 智能体
3+
description: Learn more about how to define agents in the OpenAI Agents SDK for JavaScript / TypeScript
4+
---
5+
6+
import { Code } from '@astrojs/starlight/components';
7+
import simpleAgent from '../../../../../../examples/docs/agents/simpleAgent.ts?raw';
8+
import agentWithTools from '../../../../../../examples/docs/agents/agentWithTools.ts?raw';
9+
import agentWithContext from '../../../../../../examples/docs/agents/agentWithContext.ts?raw';
10+
import agentWithAodOutputType from '../../../../../../examples/docs/agents/agentWithAodOutputType.ts?raw';
11+
import agentsAsTools from '../../../../../../examples/docs/agents/agentsAsTools.ts?raw';
12+
import agentWithHandoffs from '../../../../../../examples/docs/agents/agentWithHandoffs.ts?raw';
13+
import agentWithDynamicInstructions from '../../../../../../examples/docs/agents/agentWithDynamicInstructions.ts?raw';
14+
import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agentWithLifecycleHooks.ts?raw';
15+
import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw';
16+
import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw';
17+
18+
智能体是 OpenAI Agents SDK 的主要构建模块。**智能体** 是一个大型语言模型（LLM），它被配置了：
19+
20+
- **Instructions** —— 告诉模型*它是谁*以及*应如何响应*的系统提示。
21+
- **Model** —— 要调用的 OpenAI 模型，以及可选的模型调优参数。
22+
- **Tools** —— LLM 为完成任务可调用的一组函数或 API。
23+
24+
<Code lang="typescript" code={simpleAgent} title="基础智能体定义" />
25+
26+
本页其余部分将更详细地介绍每个智能体特性。
27+
28+
---
29+
30+
## 基础配置
31+
32+
`Agent` 构造函数接收一个配置对象。最常用的属性如下所示。
33+
34+
| 属性 | 必填 | 描述 |
35+
| --------------- | ---- | ------------------------------------------------------------------------------------------ |
36+
| `name` | 是 | 简短、易读的标识符。 |
37+
| `instructions` | 是 | 系统提示（字符串**或**函数——参见[动态 instructions](#dynamic-instructions)）。 |
38+
| `model` | 否 | 模型名称**或**自定义的 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 实现。 |
39+
| `modelSettings` | 否 | 调优参数（temperature、top_p 等）。 |
40+
| `tools` | 否 | 模型可调用的 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 实例数组。 |
41+
42+
<Code lang="typescript" code={agentWithTools} title="带有工具的智能体" />
43+
44+
---
45+
46+
## 上下文
47+
48+
智能体在其上下文类型上是**泛型化**的——即 `Agent<TContext, TOutput>`。_上下文_ 是一个依赖注入对象，由您创建并传递给 `Runner.run()`。它会被转发到每个工具、护栏、交接等组件，对于存储状态或提供共享服务（数据库连接、用户元数据、功能开关等）很有用。
49+
50+
<Code lang="typescript" code={agentWithContext} title="带有上下文的智能体" />
51+
52+
---
53+
54+
## 输出类型
55+
56+
默认情况下，智能体返回**纯文本**（`string`）。如果希望模型返回结构化对象，可以指定 `outputType` 属性。SDK 接受：
57+
58+
1. [Zod](https://github.com/colinhacks/zod) 模式（`z.object({...})`）。
59+
2. 任意兼容 JSON Schema 的对象。
60+
61+
<Code
62+
lang="typescript"
63+
code={agentWithAodOutputType}
64+
title="使用 Zod 的结构化输出"
65+
/>
66+
67+
当提供了 `outputType` 时，SDK 会自动使用
68+
[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) 而非纯文本。
69+
70+
---
71+
72+
## 多智能体系统设计模式
73+
74+
组合智能体有很多方式。我们在生产应用中经常看到两种模式：
75+
76+
1. **管理器（智能体作为工具）**——一个中心智能体掌控对话，并调用以工具形式暴露的专业智能体。
77+
2. **交接**——初始智能体在识别出用户的请求后，将整个对话委托给某个专家智能体。
78+
79+
这两种方法是互补的。管理器为您提供一个集中位置来实施护栏或速率限制，而交接让每个智能体专注于单一任务，而不必保留对对话的控制权。
80+
81+
### 管理器（智能体作为工具）
82+
83+
在这种模式下，管理器从不移交控制权——LLM 使用工具，且由管理器汇总最终答案。详见 [Tools](/openai-agents-js/zh/guides/tools#agents-as-tools)。
84+
85+
<Code lang="typescript" code={agentsAsTools} title="作为工具的智能体" />
86+
87+
### 交接
88+
89+
使用交接时，分流智能体负责路由请求，但一旦发生交接，专家智能体就拥有对话的控制权，直到产生最终输出。这使提示更短，并让您可以独立地推理每个智能体。了解更多请参阅 [Handoffs](/openai-agents-js/zh/guides/handoffs)。
90+
91+
<Code lang="typescript" code={agentWithHandoffs} title="带有交接的智能体" />
92+
93+
---
94+
95+
## 动态 instructions
96+
97+
`instructions` 可以是**函数**而非字符串。该函数接收当前的 `RunContext` 和 Agent 实例，并且可以返回字符串 _或_ `Promise<string>`。
98+
99+
<Code
100+
lang="typescript"
101+
code={agentWithDynamicInstructions}
102+
title="带有动态 instructions 的智能体"
103+
/>
104+
105+
同时支持同步和 `async` 函数。
106+
107+
---
108+
109+
## 生命周期钩子
110+
111+
对于高级用例，您可以通过监听事件来观察智能体的生命周期
112+
113+
<Code
114+
lang="typescript"
115+
code={agentWithLifecycleHooks}
116+
title="带有生命周期钩子的智能体"
117+
/>
118+
119+
---
120+
121+
## 护栏
122+
123+
护栏允许您验证或转换用户输入与智能体输出。通过 `inputGuardrails` 和 `outputGuardrails` 数组进行配置。详见 [Guardrails](/openai-agents-js/zh/guides/guardrails)。
124+
125+
---
126+
127+
## 智能体的克隆 / 复制
128+
129+
需要在现有智能体基础上做些小修改？使用 `clone()` 方法，它会返回一个全新的 `Agent` 实例。
130+
131+
<Code lang="typescript" code={agentCloning} title="克隆智能体" />
132+
133+
---
134+
135+
## 强制工具使用
136+
137+
提供工具并不保证 LLM 会调用它。您可以通过 `modelSettings.tool_choice` **强制**使用工具：
138+
139+
1. `'auto'`（默认）——LLM 决定是否使用工具。
140+
2. `'required'`——LLM _必须_ 调用某个工具（可自行选择哪个）。
141+
3. `'none'`——LLM **不得** 调用任何工具。
142+
4. 指定工具名，例如 `'calculator'` ——LLM 必须调用该特定工具。
143+
144+
<Code lang="typescript" code={agentForcingToolUse} title="强制工具使用" />
145+
146+
### 防止无限循环
147+
148+
在一次工具调用后，SDK 会自动将 `tool_choice` 重置为 `'auto'`。这可防止模型进入反复尝试调用工具的无限循环。您可以通过 `resetToolChoice` 标志或配置
149+
`toolUseBehavior` 来覆盖该行为：
150+
151+
- `'run_llm_again'`（默认）——使用工具结果再次运行 LLM。
152+
- `'stop_on_first_tool'` ——将第一个工具结果视为最终答案。
153+
- `{ stopAtToolNames: ['my_tool'] }` ——当任一列出的工具被调用时停止。
154+
- `(context, toolResults) => ...` ——返回运行是否应结束的自定义函数。
155+
156+
```typescript
157+
const agent = new Agent({
158+
...,
159+
toolUseBehavior: 'stop_on_first_tool',
160+
});
161+
```
162+
163+
---
164+
165+
## 后续步骤
166+
167+
- 了解如何 [Running Agents](/openai-agents-js/zh/guides/running-agents)。
168+
- 深入了解 [Tools](/openai-agents-js/zh/guides/tools)、[Guardrails](/openai-agents-js/zh/guides/guardrails) 和 [Models](/openai-agents-js/zh/guides/models)。
169+
- 在侧边栏的 **@openai/agents** 下查阅完整的 TypeDoc 参考。

0 commit comments

Comments
 (0)