Skip to content

Update all translated document pages #1322

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 31, 2025
Merged

Update all translated document pages #1322

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 28 additions & 31 deletions docs/ja/agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@ search:
---
# エージェント

エージェントはアプリの中核を成す構成要素です。エージェントとは、 instructions と tools で構成された大規模言語モデル ( LLM ) です。
エージェントはアプリの中核を成す基本コンポーネントです。エージェントとは、指示とツールで構成された大規模言語モデル ( LLM ) です。

## 基本設定

もっとも一般的に設定するエージェントのプロパティは次のとおりです。
エージェントで最も一般的に設定するプロパティは以下のとおりです。

- `name` : エージェントを識別する必須の文字列です。
- `instructions` : developer message または system prompt とも呼ばれます。
- `model` : 使用する LLM を指定します。また、 `model_settings` を用いて temperature や top_p などのチューニングパラメーターを任意で設定できます。
- `tools` : エージェントがタスクを遂行するために使用できる tools です。
- `name`: エージェントを識別する必須の文字列です。
- `instructions`: 開発者メッセージまたは system prompt とも呼ばれます。
- `model`: 使用する LLM と、temperature や top_p などのモデル調整パラメーターを指定する `model_settings` (任意)。
- `tools`: エージェントがタスクを達成するために使用できるツールです。

```python
from agents import Agent, ModelSettings, function_tool
Expand All @@ -33,7 +33,7 @@ agent = Agent(

## コンテキスト

エージェントは `context` 型についてジェネリックになっています。コンテキストは依存性注入のための仕組みで、あなたが作成して `Runner.run()` に渡すオブジェクトです。このオブジェクトはすべてのエージェント、 tool 、 handoff などへ引き渡され、実行時の依存関係や状態を保持する入れ物として機能します。任意の Python オブジェクトをコンテキストとして渡せます。
エージェントは `context` 型を汎用的に扱います。コンテキストは依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、実行中の依存関係や状態をまとめて保持します。任意の Python オブジェクトをコンテキストとして渡せます。

```python
@dataclass
Expand All @@ -52,7 +52,7 @@ agent = Agent[UserContext](

## 出力タイプ

デフォルトでは、エージェントはプレーンテキスト ( つまり `str` ) を出力します。特定の型で出力させたい場合は、 `output_type` パラメーターを使用します。よく使われるのは Pydantic オブジェクトですが、Pydantic の TypeAdapter にラップできる型であれば何でもサポートしています。たとえば dataclass 、 list 、 TypedDict などです。
デフォルトでは、エージェントはプレーンテキスト (すなわち `str`) を出力します。特定の型で出力させたい場合は、`output_type` パラメーターを使用します。一般的によく使われるのは [Pydantic](https://docs.pydantic.dev/) オブジェクトですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型—dataclass、list、TypedDict など—であれば何でも利用できます。

```python
from pydantic import BaseModel
Expand All @@ -73,11 +73,11 @@ agent = Agent(

!!! note

`output_type` を渡すと、モデルは通常のプレーンテキストの代わりに structured outputs を使用するよう指示されます。
`output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。

## ハンドオフ

ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡すと、エージェントは状況に応じてそれらへ委譲できます。これは、単一のタスクに特化したモジュラーなエージェントを編成できる強力なパターンです。詳細は handoffs のドキュメントをご覧ください。
ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを提供すると、エージェントは関連がある場合にそれらへ委任できます。これは単一タスクに特化したモジュール型エージェントを編成する強力なパターンです。詳細は [ハンドオフ](handoffs.md) のドキュメントをご覧ください。

```python
from agents import Agent
Expand All @@ -96,9 +96,9 @@ triage_agent = Agent(
)
```

## 動的 instructions
## 動的インストラクション

ほとんどの場合、エージェント作成時に instructions を渡しますが、関数を通じて動的に instructions を生成することもできます。その関数は agent と context を受け取り、プロンプトを返す必要があります。同期関数と async 関数の両方を指定できます。
多くの場合、エージェント作成時に instructions を指定しますが、関数を介して動的に提供することも可能です。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。同期関数と `async` 関数の両方が利用できます。

```python
def dynamic_instructions(
Expand All @@ -115,15 +115,15 @@ agent = Agent[UserContext](

## ライフサイクルイベント (hooks)

エージェントのライフサイクルを監視したい場合があります。たとえば、イベントを記録したり、特定のイベントが起きた際にデータを事前取得したりするケースです。 `hooks` プロパティを使ってエージェントのライフサイクルにフックできます。 `AgentHooks` クラスを継承し、必要なメソッドをオーバーライドしてください。
エージェントのライフサイクルを監視したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータをプリフェッチしたりするケースです。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスを継承し、必要なメソッドをオーバーライドしてください。

## ガードレール

ガードレールを使うと、エージェントの実行と並行してユーザー入力のチェックやバリデーションを行えます。たとえば、ユーザー入力の関連性をスクリーニングすることが可能です。詳細は guardrails のドキュメントを参照してください。
ガードレールを使うと、エージェント実行と並行してユーザー入力に対するチェックやバリデーションを行えます。たとえば、ユーザー入力の関連性をスクリーニングするなどです。詳細は [ガードレール](guardrails.md) のドキュメントを参照してください。

## エージェントのクローン／コピー
## エージェントのクローン作成 / コピー

エージェントの `clone()` メソッドを使うと、エージェントを複製し、必要に応じて任意のプロパティを変更できます。
エージェントの `clone()` メソッドを使用すると、エージェントを複製し、任意のプロパティを変更できます。

```python
pirate_agent = Agent(
Expand All @@ -140,12 +140,12 @@ robot_agent = pirate_agent.clone(

## ツール使用の強制

tools のリストを渡しても、 LLM が必ずしもツールを使用するとは限りません。 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は次のとおりです:
ツールのリストを渡しても、LLM が必ずしもツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。利用可能な値は以下のとおりです。

1. `auto` : LLM がツールを使うかどうかを判断します。
2. `required` : LLM にツール使用を必須とします ( どのツールを使うかは賢く選択されます )。
3. `none` : LLM にツールを使用させません。
4. 特定の文字列 ( 例 `my_tool` ) を設定すると、そのツールの使用を強制します。
1. `auto`： LLM がツールを使うかどうかを判断します。
2. `required`： LLM にツール使用を必須とします (ただし使用するツールは自動選択)。
3. `none`： LLM がツールを使用しないことを必須とします。
4. 特定の文字列 (例: `my_tool`)： LLM にそのツールの使用を必須とします。

```python
from agents import Agent, Runner, function_tool, ModelSettings
Expand All @@ -163,12 +163,11 @@ agent = Agent(
)
```

## ツール使用の挙動
## ツール使用時の挙動

`Agent` の `tool_use_behavior` パラメーターは、ツールの出力をどのように扱うかを制御します:

- `"run_llm_again"` : デフォルト。ツールを実行し、その結果を LLM が処理して最終レスポンスを生成します。
- `"stop_on_first_tool"` : 最初のツール呼び出しの出力をそのまま最終レスポンスとして使用し、以降 LLM は処理を行いません。
`Agent` の `tool_use_behavior` パラメーターは、ツール出力の処理方法を制御します。
- `"run_llm_again"`: 既定値。ツールを実行し、その結果を LLM が処理して最終応答を生成します。
- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を最終応答として使用し、追加の LLM 処理を行いません。

```python
from agents import Agent, Runner, function_tool, ModelSettings
Expand All @@ -186,8 +185,7 @@ agent = Agent(
)
```

- `StopAtTools(stop_at_tool_names=[...])` : 指定したツールが呼び出された時点で停止し、その出力を最終レスポンスとして使用します。

- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼び出された時点で停止し、その出力を最終応答として使用します。
```python
from agents import Agent, Runner, function_tool
from agents.agent import StopAtTools
Expand All @@ -209,8 +207,7 @@ agent = Agent(
tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"])
)
```

- `ToolsToFinalOutputFunction` : ツール結果を処理し、停止するか LLM を続行するかを判断するカスタム関数です。
- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM 継続かを判断するカスタム関数です。

```python
from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
Expand Down Expand Up @@ -248,4 +245,4 @@ agent = Agent(

!!! note

無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、ツール結果が LLM に送信され、その `tool_choice` により再びツール呼び出しが生成されることを繰り返すために発生します。
無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。ツール結果が LLM に送られ、その後 `tool_choice` により再度ツール呼び出しが生成され…と繰り返される無限ループを防止するためです。
26 changes: 13 additions & 13 deletions docs/ja/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ search:

## API キーとクライアント

デフォルトでは、SDK はインポートされた直後に LLM リクエストとトレーシング用の `OPENAI_API_KEY` 環境変数を参照します。アプリ起動前にこの環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使ってキーを設定できます。
デフォルトでは、SDK はインポート時に LLM リクエストおよびトレーシング用の `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にこの環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。

```python
from agents import set_default_openai_key

set_default_openai_key("sk-...")
```

別の方法として、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数もしくは上記で設定したデフォルトキーを使って `AsyncOpenAI` インスタンスを生成します。[set_default_openai_client()][agents.set_default_openai_client] 関数を使用するとこれを変更できます。
別の方法として、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数で指定された API キー、または前述の既定キーを用いて `AsyncOpenAI` インスタンスを生成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を利用してください。

```python
from openai import AsyncOpenAI
Expand All @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...")
set_default_openai_client(custom_client)
```

最後に、使用する OpenAI API をカスタマイズすることも可能です。デフォルトでは OpenAI Responses API を利用しますが、[set_default_openai_api()][agents.set_default_openai_api] 関数を用いれば Chat Completions API に変更できます。
最後に、利用する OpenAI API をカスタマイズすることも可能です。デフォルトでは OpenAI Responses API が使用されます。これを Chat Completions API に切り替えるには、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用してください。

```python
from agents import set_default_openai_api
Expand All @@ -34,35 +34,35 @@ set_default_openai_api("chat_completions")

## トレーシング

トレーシングはデフォルトで有効になっています。上記セクションで設定した OpenAI API キー（環境変数またはデフォルトキー）がそのまま使用されます。トレーシング専用の API キーを指定したい場合は、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用してください。
トレーシングはデフォルトで有効になっています。上記セクションの OpenAI API キー (環境変数または設定済みの既定キー) が自動的に使用されます。トレーシング専用の API キーを設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用してください。

```python
from agents import set_tracing_export_api_key

set_tracing_export_api_key("sk-...")
```

トレーシングを完全に無効化したい場合は、[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用できます。
トレーシングを完全に無効化したい場合は、[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を呼び出してください。

```python
from agents import set_tracing_disabled

set_tracing_disabled(True)
```

## デバッグロギング
## デバッグ ロギング

SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、警告とエラーが `stdout` に出力され、それ以外のログは抑制されます。
SDK にはハンドラーが設定されていない Python ロガーが 2 つ用意されています。デフォルトでは、warning と error は `stdout` に出力されますが、それ以外のログは抑制されています。

詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。
詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を呼び出してください。

```python
from agents import enable_verbose_stdout_logging

enable_verbose_stdout_logging()
```

また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳しくは [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。
また、ハンドラー・フィルター・フォーマッターなどを追加してログをカスタマイズすることもできます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。

```python
import logging
Expand All @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING)
logger.addHandler(logging.StreamHandler())
```

### ログに含まれる機密データ
### ログ内の機密データ

一部のログには機密データ（例: ユーザー データ）が含まれる場合があります。これらのデータをログに残したくない場合は、以下の環境変数を設定してください。
一部のログには (たとえば ユーザー データ など) 機密データが含まれる場合があります。これらを記録したくない場合は、次の環境変数を設定してください。

LLM の入力および出力のロギングを無効にするには:
LLM の入力と出力のロギングを無効にする:

```bash
export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
```

ツールの入力および出力のロギングを無効にするには:
ツールの入力と出力のロギングを無効にする:

```bash
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1
Expand Down
Loading