For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション
Theme

おすすめ

Agents API

Agents SDK

ChatKit

API ダッシュボード
ChatGPT を試す

エージェントの設定

エージェントを定義し、設定を再利用しながらセッションごとにカスタマイズできます。

エージェントの動作は設定で決まります。設定はセッションの作成時に指定することも、保存して再利用することもできます。会話と作業内容はセッションに保持され、再利用できる設定は保存済みのエージェントに保持されます。

エージェントの動作の定義

まずモデルと指示を指定し、次にタスクに必要なツールや設定を追加します。

  • モデル： タスクを実行するモデル
  • 指示： エージェントが行うことと、その際の振る舞い方
  • ツール： ウェブ検索や独自の関数の呼び出しなど、エージェントが実行できる操作
  • 推論と出力： モデルの推論強度、応答の形式と詳しさ

セッションを作成するときに、これらの設定を agent に渡します。次の例では、モデル、指示、ユーザーの最初のメッセージを指定しています。

単一セッションでのエージェントの設定
from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Answer the user clearly and concisely.",
    },
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "What can you help with?"}],
        }
    ],
)
print(session.to_json())

設定フィールドと指定できる値については、Agents API リファレンスを参照してください。各機能の設定方法は、関数、コンピューターの使用、MCP 接続、複数のエージェント間でのタスクの委任を参照してください。

設定のサイズ

指示とツール設定の合計サイズは 4 MiB（4,194,304 バイト）未満に抑え、Agents API のメタデータ用に少し余裕を残してください。設定が大きすぎてセッションを開始できない場合は、指示とツール設定のサイズを小さくして、新しいセッションを作成してください。

環境にアップロードするファイルには、別途ファイルの上限が適用されます。

複数のセッションでのエージェントの再利用

エージェントを保存すると、複数のセッションで同じ設定を再利用できます。エージェントを一度作成したら、各セッションの開始時にその ID を agent_id として渡します。

エージェントの再利用
from openai import OpenAI

client = OpenAI()
agent = client.beta.agents.create(
    model="gpt-6-astra",
    instructions="Answer technical questions accurately.",
    reasoning={"summary": "auto"},
    timeout=360,
)
session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="Explain how an agent connects to an MCP server.",
)
print(session.to_json())

会話と作業内容はセッションごとに独立しています。保存済みエージェントの一覧表示、取得、更新、削除については、Agents API リファレンスを参照してください。認証情報は、保存済みの設定とは別にボールトに保管されます。

保存済みエージェントの更新

保存済みエージェントへの変更は、新しいセッションにのみ適用されます。各セッションは作成時に保存済みの設定をコピーし、以降のターンでもその設定を使用します。既存のセッションを変更するには、そのセッションの設定を更新してください。

保存済みエージェントを更新するときは、次のルールが適用されます。

  • 省略したフィールドには保存済みの値が残ります。model だけを変更した場合、reasoning、service_tier、text の値は保持されます。
  • オブジェクトを指定すると、フィールド全体が置き換わります。reasoning に effort だけを指定すると、保存済みの summary もクリアされます。
  • null を受け付けるフィールドは、この値を指定するとリセットされます。たとえば、reasoning: null を指定すると、推論強度がモデルのデフォルト値に戻ります。

新しいモデルがサポートしていない設定は、同じリクエストで変更またはリセットしてください。

単一セッションでの設定の上書き

保存済みエージェントの設定をカスタマイズするには、セッションの作成時に agent_id と agent の両方を指定します。モデルを含め、省略した設定は作成時に保存済みエージェントからセッションにコピーされます。

次の例を実行する前に、例示用の値 agent_123 を保存済みエージェントの ID に置き換えてください。

単一セッションでのエージェント設定の上書き
# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI

client = OpenAI()

agent_id = "agent_123"
session = client.beta.agents.sessions.create(
    agent_id=agent_id,
    agent={"instructions": "Answer this question in one concise paragraph."},
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Explain how an agent connects to an MCP server.",
                }
            ],
        }
    ],
)
print(session.to_json())

上書きはそのセッションにのみ適用されます。保存済みエージェントや他のセッションの設定は変わりません。オブジェクトや配列を指定すると、保存済みの値とマージされず、フィールド全体が置き換わります。たとえば、tools を指定すると、保存済みのツール一覧が置き換わります。

リクエストのフィールドについては、セッション作成のリファレンスを参照してください。

既存セッションの設定の更新

POST /v1/agents/sessions/{session_id} に agent オブジェクトを含むリクエストを送ると、そのセッションの tools、model、reasoning.effort、service_tier を変更できます。これらの設定はベータ版と一般提供版（GA）のどちらの API 仕様でも利用できます。同じリクエストで metadata も更新できます。

モデル、推論強度、サービスティアの変更は、更新完了後に送信したメッセージで始まる新しいターンに適用されます。すでに送信され、処理が完了していないメッセージには、更新前の設定が使われる場合があります。進行中のターンでは、途中で追加の指示を送っても、これら 3 項目はそのターンの開始時の設定のままです。セッションの会話履歴も保持されます。選択したモデルが更新後の設定をサポートしていない場合、更新は失敗します。

  • agent オブジェクトと reasoning オブジェクトでは、指定したフィールドが現在の設定にマージされます。推論の要約を含め、省略したフィールドの値は変わりません。model だけを変更した場合、セッションの推論強度とサービスティアは保持されます。
  • tools を指定すると、ツール一覧全体が置き換わります。関数と MCP サーバーの変更は次のモデル呼び出し時に反映されます。組み込みツールの変更は次のターンまでに反映されます。現在のツールを保持するには tools を省略し、すべてクリアするには null または [] を渡してください。
  • reasoning.effort: null を指定すると、推論強度が選択したモデルのデフォルト値に戻ります。
  • service_tier: null を指定すると、サービスティアの自動選択に戻ります。
  • モデルは常に設定されている必要があるため、model: null は指定できません。agent オブジェクトと reasoning オブジェクトにも null は指定できません。
  • metadata を指定すると、マップ全体が置き換わります。メタデータを保持するにはこのフィールドを省略し、クリアするには null または {} を渡してください。

たとえば、次のリクエストは推論強度を変更し、サービスティアを API が自動で選択するように設定します。

{
  "agent": {
    "reasoning": { "effort": "low" },
    "service_tier": null
  }
}

セッションを更新しても、保存済みエージェントや他のセッションの設定は変わりません。その後、保存済みエージェントを更新しても、このセッションの設定は変わりません。

このエンドポイントでは、reasoning.summary、text、instructions、multi_agent を更新できません。これらの設定を変更するには、新しいセッションを作成してください。リクエストのフィールドについては、セッション更新のリファレンスを参照してください。

操作の承認リクエストの自動レビュー

セッションレベルの review フィールドを "auto_review" に設定すると、対象の承認リクエストが自動的にレビューされます。このフィールドはエージェント設定の外側で、agent または agent_id と同じ階層に指定してください。セッションの作成時に review を省略すると、デフォルト値の "none" が使われます。

自動レビューを有効にすると、実行権限も変わります。有効にする前に、環境の前提条件を確認してください。

review を更新できるのは、メインタスクがアイドル状態で、入力の送信処理も完了しているときです。以降の実行と復旧には、新しい設定が使われます。これらの条件がそろう前にモードの変更をリクエストすると、409 Conflict が返され、変更は適用されません。自動レビューが有効なプロジェクトと、自動レビューに対応したセッションを使用してください。設定方法と承認リクエストの処理については、自動レビューを参照してください。

環境の設定

セッションの作成時に environment を agent とあわせて指定します。この設定で、エージェントがコマンドを実行したりファイルを操作したりする環境が決まります。

none、openai_hosted、self_hosted のいずれかを選択します。アーキテクチャでは、各オプションの使い分けと、それぞれの環境を誰が管理するかを説明しています。

OpenAI がホストする環境では、コンテナのサイズを選択し、タスクに必要なパッケージ、初期ファイル、ネットワークアクセスを設定します。環境テンプレートは複数のセッションで再利用できます。セルフホスト環境では、自分でコンピューティングリソースを用意し、エグゼキューターを接続します。

環境の設定フィールドについてはセッション作成のリファレンスを、スキル、プラグイン、テンプレートについてはプラグインを参照してください。実行後もファイルを保持する方法については、セッションの成果物を参照してください。