Skip to content

Update all translated document pages #1400

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

Closed
wants to merge 1 commit into from
Closed

Update all translated document pages #1400

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
62 changes: 32 additions & 30 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 ) です。
エージェントは、アプリの中心的な構成要素です。エージェントとは、 instructions とツールで設定された大規模言語モデル（ LLM ）です。

## 基本設定

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

- `name`: エージェントを識別する必須の文字列です。
- `instructions`: developer message または system prompt とも呼ばれます。
- `model`: 使用する LLM と、 temperature や top_p などのモデル調整パラメーターを指定できる `model_settings` ( 任意 )。
- `tools`: エージェントがタスクを達成するために使用できる tools です。
- `name`: エージェントを識別する必須の文字列。
- `instructions`: developer message や system prompt とも呼ばれます。
- `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` の型がジェネリックです。 context は依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、 tool、 handoff などに渡され、依存関係や実行時の状態をまとめて保持します。 context には任意の Python オブジェクトを渡せます。
エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、`Runner.run()` に渡すオブジェクトです。このオブジェクトはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係や状態を入れておく入れ物として機能します。任意の Python オブジェクトをコンテキストとして渡せます。

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

## 出力タイプ

デフォルトでは、エージェントはプレーンテキスト ( つまり `str` ) を出力します。特定の型で出力させたい場合は `output_type` パラメーターを使用します。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを使いますが、 dataclass や list、 TypedDict など、 Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型なら何でも対応しています。
デフォルトでは、エージェントはプレーンテキスト ( つまり `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 を使用するよう指示されます。

## ハンドオフ

ハンドオフは、エージェントが委任できるサブエージェントです。 handoffs のリストを渡すと、エージェントは必要に応じてそれらに委任できます。これは、単一タスクに特化したモジュール化されたエージェントを編成する強力なパターンです。詳細は [ハンドオフ](handoffs.md) ドキュメントをご覧ください。
ハンドオフは、エージェントが処理を委任できるサブエージェントです。ハンドオフのリストを提供すると、必要に応じてエージェントはそれらへ委任できます。これにより、単一タスクに特化したモジュール式のエージェントを編成できる強力なパターンが実現します。詳細は [handoffs](handoffs.md) のドキュメントをご覧ください。

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

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

多くの場合、エージェント作成時に instructions を渡しますが、関数を介して動的に instructions を生成することもできます。この関数は agent と context を受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方に対応しています。
通常、エージェント作成時に instructions を渡しますが、関数を介して動的に instructions を生成することもできます。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数でも `async` 関数でも構いません。

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

## ライフサイクルイベント ( hooks )
## ライフサイクルイベント (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 @@ -138,14 +138,14 @@ robot_agent = pirate_agent.clone(
)
```

## ツール利用の強制
## ツール使用の強制

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

1. `auto` : LLM が tool を使うかどうかを決定します。
2. `required` : LLM に tool の使用を必須にします ( どの tool を使うかは自動で判断 )。
3. `none` : LLM に tool を _使わない_ ことを要求します。
4. 具体的な文字列 ( 例: `my_tool` ) を指定すると、その特定の 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,11 @@ agent = Agent(
)
```

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

`Agent` の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。
- `"run_llm_again"` : 既定値。 tool を実行し、その結果を LLM が処理して最終応答を生成します。
- `"stop_on_first_tool"` : 最初の 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 +185,8 @@ agent = Agent(
)
```

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

```python
from agents import Agent, Runner, function_tool
from agents.agent import StopAtTools
Expand All @@ -207,7 +208,8 @@ agent = Agent(
tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"])
)
```
- `ToolsToFinalOutputFunction`: tool の結果を処理し、 LLM を続行するか停止するかを判断するカスタム関数です。

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

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

!!! note

無限ループを防ぐため、フレームワークは tool 呼び出し後に `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 は環境変数または上記で設定したデフォルトキーを用いて `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 キー（環境変数または設定したデフォルトキー）を使用します。トレーシング専用の 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 つあります。デフォルトでは、警告とエラーは `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