エージェントの設定

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

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

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

モデル： 作業に使用するモデル
指示： エージェントが行うべきことと、その振る舞い方
ツール： ウェブ検索や独自の関数の呼び出しなど、エージェントが実行できるアクション
推論と出力： モデルの推論量、および応答の形式と詳しさ

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

単一セッション用のエージェント設定

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import OpenAI from "openai";
const client = new OpenAI();

const session = await 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?",
        },
      ],
    },
  ],
});

console.log(session);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18from 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())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("Answer the user clearly and concisely."),
		},
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input: openai.BetaAgentSessionNewParamsInputUnion{
			OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
				{
					Content: []openai.InputContentParamUnion{
						{
							OfParamInputText: &openai.InputContentParamInputText{Text: "What can you help with?"},
						},
					},
				},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions("Answer the user clearly and concisely.")
                        .build())
                .environmentNone()
                .input("What can you help with?")
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22require "openai"

client = OpenAI::Client.new
result = 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?"
        }
      ]
    }
  ]
)
puts result

設定フィールドと指定可能な値については、Agents API リファレンスを参照してください。ツールのセットアップについては関数と MCP 接続を、委任についてはマルチエージェントを参照してください。

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

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

エージェントの再利用

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from 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())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
agent, err := client.Beta.Agents.New(ctx,
	openai.BetaAgentNewParams{
		Model:        "gpt-6-astra",
		Instructions: openai.String("Answer technical questions accurately."),
		Reasoning:    openai.AgentReasoningParam{Summary: "auto"},
	})
if err != nil {
	panic(err)
}
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		AgentID:     openai.String(agent.ID),
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input:       openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Explain how an agent connects to an MCP server.")},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentCreateParams;
import com.openai.models.beta.agents.AgentReasoningParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var agent =
    client
        .beta()
        .agents()
        .create(
            AgentCreateParams.builder()
                .model("gpt-6-astra")
                .instructions("Answer technical questions accurately.")
                .reasoning(
                    AgentReasoningParam.builder()
                        .summary(AgentReasoningParam.Summary.of("auto"))
                        .build())
                .build());
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agentId(agent.id())
                .environmentNone()
                .input("Explain how an agent connects to an MCP server.")
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

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

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

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

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

保存済みエージェントを更新する際は、次の点に注意してください。

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

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

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

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

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

単一セッションでのエージェント設定の上書き

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();

const agentId = "agent_123";
const session = await client.beta.agents.sessions.create({
  agent_id: agentId,
  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.",
        },
      ],
    },
  ],
});

console.log(session);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# 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())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31// Replace the illustrative IDs and URLs below with your own resource values.
import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		AgentID:     openai.String("agent_123"),
		Agent:       openai.BetaAgentSessionNewParamsAgent{Instructions: openai.String("Answer this question in one concise paragraph.")},
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input: openai.BetaAgentSessionNewParamsInputUnion{
			OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
				{
					Content: []openai.InputContentParamUnion{
						{
							OfParamInputText: &openai.InputContentParamInputText{Text: "Explain how an agent connects to an MCP server."},
						},
					},
				},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22// Replace the illustrative IDs and URLs below with your own resource values.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agentId("agent_123")
                .agent(
                    SessionCreateParams.Agent.builder()
                        .instructions("Answer this question in one concise paragraph.")
                        .build())
                .environmentNone()
                .input("Explain how an agent connects to an MCP server.")
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21# Replace the illustrative IDs and URLs below with your own resource values.
require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent_id: "agent_123",
  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."
        }
      ]
    }
  ]
)
puts result

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

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

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

単一セッションの model、reasoning.effort、service_tier を変更するには、agent オブジェクトを含む POST /v1/agents/sessions/{session_id} リクエストを送信してください。これらの設定は、ベータ版と GA 版の API 仕様で利用できます。同じリクエストで metadata も更新できます。

変更は、更新完了後に送信したメッセージによって開始される新しいターンに適用されます。すでに処理中のメッセージには、変更前の設定が使われる場合があります。進行中のターンでは、方向修正のメッセージを送信した場合も、そのターンの設定が保持されます。セッションの会話履歴も保持されます。選択したモデルが更新後の設定をサポートしていない場合、更新は失敗します。

agent オブジェクトと reasoning オブジェクトでは、指定したフィールドが現在の設定にマージされます。推論の要約を含め、省略したフィールドは変更されません。model のみを変更した場合、セッションの推論強度とサービスティアは保持されます。
reasoning.effort: null を指定すると、推論強度が選択したモデルのデフォルト値にリセットされます。
service_tier: null を指定すると、サービスティアが自動選択に戻ります。
モデルは常に設定されている必要があるため、model: null は指定できません。agent オブジェクトと reasoning オブジェクトも null を受け付けません。
metadata を指定すると、マップ全体が置き換えられます。メタデータを保持するには省略し、クリアするには null または {} を渡してください。

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

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

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

このエンドポイントでは、reasoning.summary、text、tools、instructions、multi_agent は更新できません。これらの設定を変更するには、新しいセッションを作成してください。

環境設定

セッションの作成時に、agent とともに environment を設定します。これにより、エージェントがコマンドを実行し、ファイルを扱う環境が決まります。

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

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

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

おすすめ

はじめに

基本コンセプト

SDK と CLI

リソース

レガシー API

モデルの選び方

テキストとコード

プロンプト

推論

画像と動画

リアルタイムと音声

特化型モデル

Agents API

Agents SDK

ChatKit

検索と取得

ツールとデータの接続

ツールを使ったワークフローの構築

コンピューターとコード

メディア

GPT-Live

Realtime API

音声を活用した開発

接続

音声処理

本番運用の開始

性能と品質

コストとスループット

安全性とガバナンス

インフラとアクセス

オペレーション

基本コンセプト

Plan

Build

Test and publish

Conversion specs

ガイド

リソース

はじめに

ガイド

File Upload

API

Measurement

Advertiser API

API リファレンス

はじめに

基礎

詳しく見る

利用可能な環境

リリース

ワークフロー

できること

リファレンス

カスタマイズ

設定ファイル

エージェントの構成

ChatGPT と Codex の機能拡張

Linux

Windows

開発ワークフロー

拡張と自動化

環境

Codex を使った開発

サードパーティ連携

リファレンス

権限

Codex Security

サイバーセーフティ

はじめに

ChatGPT Work

ID と認証

ワークスペースのアクセス、ポリシー、モデル

プラグインとコネクタの制御

利用状況、ガバナンス、コンプライアンス

展開とモデルプロバイダー

コミュニティ

ブログ

コミュニティ

ブログ