Skip to content

Update all translated document pages #1308

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 30, 2025
Merged

Update all translated document pages #1308

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: 30 additions & 29 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:
---
# エージェント

エージェントはアプリの中心的な構成要素です。エージェントとは、指示とツールで構成された大規模言語モデル（ LLM ）です。
エージェント は、アプリの中心的なビルディングブロックです。エージェント は、指示 (`instructions`) とツール (`tools`) で構成された LLM です。

## 基本設定

エージェントを設定する際によく使うプロパティは次のとおりです。
エージェント で最もよく設定するプロパティは次のとおりです。

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

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

## コンテキスト

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

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

## 出力タイプ

デフォルトでは、エージェントはプレーンテキスト（`str`）を出力します。特定の型で出力させたい場合は `output_type` パラメーターを使用します。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを指定しますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型（ dataclass、リスト、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](https://platform.openai.com/docs/guides/structured-outputs) を使用するようになります。
`output_type` を渡すと、モデルは通常のプレーンテキストではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。

## ハンドオフ

ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡すと、エージェントは必要に応じてそれらに委譲します。これにより、単一タスクに特化したモジュール型のエージェントをオーケストレーションする強力なパターンが実現します。詳細は [handoffs](handoffs.md) ドキュメントをご覧ください。
ハンドオフ は、エージェント が委譲できるサブエージェントです。ハンドオフ のリストを渡すことで、関連性がある場合にエージェント がそれらへ委譲できます。これは、単一タスクに特化したモジュール化 エージェント をオーケストレーションする強力なパターンです。詳細は [ハンドオフ](handoffs.md) ドキュメントを参照してください。

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

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

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

```python
def dynamic_instructions(
Expand All @@ -113,17 +113,17 @@ agent = Agent[UserContext](
)
```

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

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

## ガードレール

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

## エージェントのクローン／コピー
## エージェントの複製とコピー

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

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

## ツール使用の強制

ツールをリストで渡しても、必ずしも 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`) : 指定したツールを必ず使用させます。

```python
from agents import Agent, Runner, function_tool, ModelSettings
Expand All @@ -163,11 +163,12 @@ 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 @@ -185,7 +186,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 @@ -207,7 +208,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 @@ -245,4 +246,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` により LLM が再度ツールを呼び出し…という処理が繰り返されることで発生します。
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 は環境変数にある API キー、または上記で設定したデフォルトキーを使用して `AsyncOpenAI` インスタンスを生成します。[set_default_openai_client()][agents.set_default_openai_client] 関数を使うことで、これを変更できます。
代わりに、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は環境変数または上記で設定したデフォルトキーを使って `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 を使用していますが、 [set_default_openai_api()][agents.set_default_openai_api] 関数を使って Chat Completions API に変更できます。

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

## トレーシング

トレーシングはデフォルトで有効になっています。デフォルトでは、上記の OpenAI API キー（つまり環境変数またはあなたが設定したデフォルトキー）を使用します。[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使って、トレーシング専用の API キーを設定できます。
トレーシングはデフォルトで有効です。デフォルトでは、上記セクションで説明した 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 つあります。デフォルトでは、警告とエラーが `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