エージェントはアプリの中核となる基本コンポーネントです。エージェントは、instructions と tools で構成された大規模言語モデル（ LLM ）です。

- `instructions`: developer message または system prompt とも呼ばれます。

- `model`: 使用する LLM と、temperature、top_p などのモデル調整パラメーターを設定する任意の `model_settings` です。

- `tools`: エージェントがタスク達成のために使用できるツールです。

エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェントの実行における依存関係や状態を格納するための入れ物として機能します。コンテキストには任意の Python オブジェクトを提供できます。

デフォルトでは、エージェントはプレーンテキスト（すなわち `str`）出力を生成します。特定のタイプの出力を生成したい場合は、`output_type` パラメーターを使用できます。一般的な選択肢としては [Pydantic](https://docs.pydantic.dev/) オブジェクトがありますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップ可能な任意の型（dataclasses、lists、TypedDict など）をサポートしています。

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

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

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

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

ガードレールを使用すると、エージェントの実行と並行してユーザー入力に対するチェック／バリデーションを実行し、エージェントの出力が生成された後にもチェックできます。たとえば、ユーザー入力とエージェントの出力の関連性をスクリーニングできます。詳しくは [ガードレール](guardrails.md) ドキュメントをご覧ください。

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

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

1. `auto`：LLM がツールを使うかどうかを判断します。

2. `required`：LLM にツールの使用を要求します（ただし、どのツールを使うかは賢く判断できます）。

3. `none`：LLM にツールを使用しないことを要求します。

4. 特定の文字列を設定（例: `my_tool`）：LLM にその特定のツールの使用を要求します。

`Agent` の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。

- `"run_llm_again"`: デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。

- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を最終応答として使用し、以後の LLM 処理は行いません。

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

無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループが起こるのは、ツールの結果が LLM に送られ、`tool_choice` により LLM がさらにツール呼び出しを生成し続けるためです。

デフォルトでは、 SDK はインポートされるとすぐに、 LLM リクエストとトレーシングのために `OPENAI_API_KEY` 環境変数を探します。アプリが起動する前にその環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。

また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は `AsyncOpenAI` インスタンスを作成し、上記の環境変数またはデフォルトキーから API キーを使用します。これを変更するには、 [set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。

最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用します。 [set_default_openai_api()][agents.set_default_openai_api] 関数で、 Chat Completions API を使うように上書きできます。

トレーシングはデフォルトで有効です。デフォルトでは、上記の OpenAI API キー（つまり環境変数または設定したデフォルトキー）を使用します。トレーシングに使用する API キーを個別に設定するには、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。

[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用すると、トレーシングを完全に無効にすることもできます。

SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、これは警告とエラーが `stdout` に送られ、それ以外のログは抑制されることを意味します。

冗長なログを有効にするには、 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。

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

一部のログには機微データ（例: ユーザー データ）が含まれる場合があります。これらのデータを記録しないようにするには、次の環境変数を設定してください。