Skip to content

Commit ba05de9

Browse files
seratchseratch
authored
Update tools document page (#6)
1 parent d73154a commit ba05de9

File tree

2 files changed

+40
-39
lines changed

2 files changed

+40
-39
lines changed

‎docs/src/content/docs/guides/tools.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import agentsAsToolsExample from '../../../../../examples/docs/tools/agentsAsToo
1212
Tools let an Agent **take actions** – fetch data, call external APIs, execute code, or even use a
1313
computer. The JavaScript/TypeScript SDK supports three categories:
1414

15-
1. **Hosted tools** – run alongside the model on OpenAI servers. _(web search, file search, computer use)_
15+
1. **Hosted tools** – run alongside the model on OpenAI servers. _(web search, file search, computer use, code interpreter, image generation)_
1616
2. **Function tools** – wrap any local function with a JSON schema so the LLM can call it.
1717
3. **Agents as tools** – expose an entire Agent as a callable tool.
1818

‎docs/src/content/docs/ja/guides/tools.mdx‎

Lines changed: 39 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -9,35 +9,36 @@ import toolsHostedToolsExample from '../../../../../../examples/docs/tools/hoste
99
import nonStrictSchemaTools from '../../../../../../examples/docs/tools/nonStrictSchemaTools.ts?raw';
1010
import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAsTools.ts?raw';
1111

12-
ツールを使うと Agent は **アクションを実行** できます。たとえばデータ取得、外部 API 呼び出し、コード実行、さらにはコンピュータ操作などです。JavaScript/TypeScript SDK は次の 3 つのカテゴリーをサポートします。
12+
ツールを使うとエージェントが **アクションを実行** できます。たとえばデータ取得、外部 API 呼び出し、コード実行、さらにはコンピュータ操作まで行えます。JavaScript / TypeScript SDK では次の 3 つのカテゴリーをサポートしています。
1313

14-
1. **組み込みツール（Hosted）** – モデルと同じ OpenAI サーバー上で動作します。 _(web search, file search, computer use)_
15-
2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM から呼び出せるようにします。
16-
3. **エージェントをツールとして使用** – エージェント全体を呼び出し可能なツールとして公開します。
14+
1. **組み込みツール（Hosted）** – OpenAI のサーバー上でモデルと一緒に動作
15+
_(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)_
16+
2. **関数ツール** – 任意のローカル関数を JSON スキーマでラップし、LLM が呼び出せるようにする
17+
3. **エージェントをツールとして公開** – エージェント全体を呼び出し可能なツールとして公開
1718

1819
---
1920

2021
## 1. 組み込みツール（Hosted）
2122

22-
`OpenAIResponsesModel` を使用する際、以下の組み込みツールを追加できます。
23+
`OpenAIResponsesModel` を使用する際、以下のビルトインツールを追加できます。
2324

24-
| ツール | Type string | 目的 |
25-
| ----------------------- | -------------------- | --------------------------------------- |
26-
| Web search | `'web_search'` | インターネット検索 |
27-
| File / retrieval search | `'file_search'` | OpenAI がホストするベクトルストアの検索 |
28-
| Computer use | `'computer'` | GUI 操作の自動化 |
29-
| Code Interpreter | `'code_interpreter'` | サンドボックス環境でのコード実行 |
30-
| Image generation | `'image_generation'` | テキストを元に画像を生成 |
25+
| ツール | type 文字列 | 目的 |
26+
| ---------------- | -------------------- | --------------------------------------- |
27+
| Web 検索 | `'web_search'` | インターネット検索 |
28+
| ファイル / 検索 | `'file_search'` | OpenAI がホストするベクトルストアの検索 |
29+
| コンピュータ操作 | `'computer'` | GUI 操作を自動化 |
30+
| Code Interpreter | `'code_interpreter'` | サンドボックス環境でコードを実行 |
31+
| 画像生成 | `'image_generation'` | テキストから画像を生成 |
3132

3233
<Code lang="typescript" code={toolsHostedToolsExample} title="Hosted tools" />
3334

34-
各ツールのパラメーターは OpenAI Responses API と完全に一致します。`rankingOptions` やセマンティックフィルターなどの高度なオプションについては公式ドキュメントを参照してください。
35+
各ツールのパラメーターは OpenAI Responses API と同一です。`rankingOptions` やセマンティックフィルターなど詳細は公式ドキュメントをご覧ください。
3536

3637
---
3738

3839
## 2. 関数ツール
3940

40-
`tool()` ヘルパーを使えば **あらゆる** 関数をツール化できます。
41+
`tool()` ヘルパーを使えば **どんな** 関数でもツールに変換できます。
4142

4243
<Code
4344
lang="typescript"
@@ -47,18 +48,18 @@ import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAs
4748

4849
### オプションリファレンス
4950

50-
| フィールド | 必須 | 説明 |
51-
| --------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
52-
| `name` | No | 省略時は関数名（例: `get_weather`）が使用されます |
53-
| `description` | Yes | LLM に表示される人間が読めるわかりやすい説明 |
54-
| `parameters` | Yes | Zod スキーマまたは元 JSON スキーマオブジェクト。Zod を使うと自動的に **strict** モードが有効になります |
55-
| `strict` | No | `true`（デフォルト）の場合、引数が検証に失敗すると SDK はモデルエラーを返します。曖昧な入力を許容するには `false` に設定します |
56-
| `execute` | Yes | `(args, context) => string \| Promise<string>` – ビジネスロジック。第 2 引数は任意で `RunContext` |
57-
| `errorFunction` | No | 内部エラーをユーザー向け文字列に変換するカスタムハンドラー `(context, error) => string` |
51+
| フィールド | 必須 | 説明 |
52+
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
53+
| `name` | いいえ | 関数名がデフォルト（例: `get_weather`） |
54+
| `description` | はい | LLM に表示される、わかりやすい説明 |
55+
| `parameters` | はい | Zod スキーマまたは元の JSON スキーマオブジェクト。Zod を使うと自動的に **strict** モードが有効になります |
56+
| `strict` | いいえ | `true`（デフォルト）で、引数が検証に失敗するとモデルエラーを返します。曖昧入力を許可する場合は `false` に設定 |
57+
| `execute` | はい | `(args, context) => string \| Promise<string>` – ビジネスロジック。第 2 引数は省略可能で `RunContext` |
58+
| `errorFunction` | いいえ | 内部エラーをユーザー可視の文字列へ変換するカスタムハンドラー `(context, error) => string` |
5859

59-
### 非 strict JSON-schema ツール
60+
### 非 strict JSON スキーマツール
6061

61-
不完全または無効な入力を _推測_ させたい場合は、strict モードを無効にして元 JSON スキーマを使用できます。
62+
無効または部分的な入力をモデルに _推測_ させたい場合は、raw JSON スキーマ使用時に strict モードを無効化できます。
6263

6364
<Code
6465
lang="typescript"
@@ -68,37 +69,37 @@ import agentsAsToolsExample from '../../../../../../examples/docs/tools/agentsAs
6869

6970
---
7071

71-
## 3. ツールとしてのエージェント
72+
## 3. エージェントをツールとして公開
7273

73-
会話を完全に引き渡すのではなく、別のエージェントを _補助_ として使いたい場合は `agent.asTool()` を利用します。
74+
会話を完全に引き渡さず、あるエージェントが別エージェントを _支援_ したい場合に `agent.asTool()` を利用します。
7475

7576
<Code lang="typescript" code={agentsAsToolsExample} title="Agents as tools" />
7677

77-
内部では SDK が以下を行います。
78+
SDK 内部では以下を行います。
7879

79-
- `input` パラメーター 1 つの関数ツールを生成
80-
- ツール呼び出し時にサブエージェントをその入力で実行
80+
- `input` パラメーター 1 つだけの関数ツールを作成
81+
- ツール呼び出し時にその入力でサブエージェントを実行
8182
- 最後のメッセージ、または `customOutputExtractor` が抽出した出力を返却
8283

8384
---
8485

85-
## ツール使用時の挙動
86+
## ツール使用の挙動
8687

87-
モデルにツールを必ず使用させるタイミング・方法の制御（`tool_choice`, `toolUseBehavior` など）については [エージェント](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照してください。
88+
モデルにツール使用を必須化する方法などは [エージェント](/openai-agents-js/guides/agents#forcing-tool-use) を参照してください (`tool_choice`、`toolUseBehavior` など)。
8889

8990
---
9091

9192
## ベストプラクティス
9293

93-
- **短く明確な説明** – ツールが _何をするか_ と _いつ使うべきか_ を記述する
94-
- **入力を検証** – 可能な限り Zod スキーマで厳密な JSON 検証を行う
95-
- **エラーハンドラーで副作用を避ける** – `errorFunction` は有用な文字列を返すだけにし、throw しない
96-
- **ツールは単機能に** – 小さく再利用可能なツールの方がモデルの推論品質が向上する
94+
- **短く明確な説明** – ツールが _何を行い、いつ使うか_ を具体的に記述
95+
- **入力を検証** – 可能なら Zod スキーマで厳格な JSON 検証を実施
96+
- **エラーハンドラーで副作用を避ける** – `errorFunction` は有益な文字列を返すだけにし、例外を投げない
97+
- **ツールは単一責務** – 小さく再利用可能なツールはモデルの推論を助けます
9798

9899
---
99100

100101
## 次のステップ
101102

102-
- [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) について学ぶ
103-
- [ガードレール](/openai-agents-js/ja/guides/guardrails) を追加してツールの入力・出力を検証
104-
- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツール型の TypeDoc リファレンスを確認
103+
- [ツール使用の強制](/openai-agents-js/guides/agents#forcing-tool-use) を学習
104+
- [ガードレール](/openai-agents-js/guides/guardrails) を追加してツールの入力・出力を検証
105+
- [`tool()`](/openai-agents-js/openai/agents/functions/tool) と各種組み込みツール型の TypeDoc リファレンスを掘り下げる

0 commit comments

Comments
 (0)