セッションの実行と継続

セッションには、エージェントの設定、会話、保存済みの作業内容が保持されます。同じセッションに追加のメッセージを送ると、作業を続けられます。

セッションとターン

ターンとは、セッション内で行う一連の作業の単位です。待機中のセッションにメッセージを送ると、新しいターンが始まります。ターンの実行中にメッセージを送ると、そのターンの作業に追加の指示を出せます。

ターンは非同期で実行されます。アプリケーションでは、ストリーミングで進捗を確認したり、Webhook でセッションの状態変化を受け取ったりできます。

スケジュール設定したオートメーションを使うと、指定した日時に、または定期的に作業を開始できます。オートメーションでは、実行のたびに新しいセッションを作成することも、既存の会話を続けることもできます。

作業の開始

エージェントの設定と最初の input を指定してセッションを作成します。stream を true に設定すると、同じリクエストで最初のターンのイベントを受け取れます。

API キーと SDK を設定したら、次の例を実行してスクリプトを作成し、実行します。スクリプトの実行環境は OpenAI が管理します。

セッションの作成と最初のターンのストリーミング

Python

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

const client = new OpenAI();
const events = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions: "Write clean code, run it, and report the actual output.",
  },
  environment: { type: "openai_hosted" },
  input:
    "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
  stream: true,
});
events.withResultCollection();
try {
  for await (const event of events) {
    console.log(JSON.stringify(event));
  }
  const result = await events.finalResult();
  console.log(result.output_text);
  console.log("Session:", result.session_id);
} finally {
  events.controller.abort();
}

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

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ).with_result_collection() as stream:
        for event in stream:
            print(event.to_json(indent=None), flush=True)
        result = stream.get_final_result()
    print(result.output_text)
    session_id = result.session_id

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
32
33
34
35import (
	"context"
	"fmt"

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

ctx := context.Background()
client := openai.NewClient()
events := client.Beta.Agents.Sessions.NewStreaming(ctx, openai.BetaAgentSessionNewParams{
	Agent: openai.BetaAgentSessionNewParamsAgent{
		Model:        openai.String("gpt-6-astra"),
		Instructions: openai.String("Write clean code, run it, and report the actual output."),
	},
	Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{}},
	Input: openai.BetaAgentSessionNewParamsInputUnion{
		OfString: openai.String("Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output."),
	},
})
defer events.Close()
openai.BetaAgentSessionWithResultCollection(events)
if events.Err() != nil {
	panic(events.Err())
}
for events.Next() {
	event := events.Current()
	fmt.Println(event.RawJSON())
}
result, err := openai.BetaAgentSessionFinalResult(events)
if err != nil {
	panic(err)
}
fmt.Println(result.OutputText())
sessionID := result.SessionID()
fmt.Println("Session:", sessionID)

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
32
33
34
35
36
37
38
39import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.ObjectMappers;
import com.openai.core.http.StreamResponse;
import com.openai.models.beta.agents.AgentSessionEvent;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import com.openai.services.beta.agents.AgentTurnResults;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var json = ObjectMappers.jsonMapper();
try (StreamResponse<AgentSessionEvent> events =
    client
        .beta()
        .agents()
        .sessions()
        .createStreaming(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions("Write clean code, run it, and report the actual output.")
                        .build())
                .environment(EnvironmentParam.OpenAIHosted.builder().build())
                .input(
                    "Create tree.py, a Python script that prints a readable tree of the files"
                        + " in the current directory. Run it and show me the output.")
                .build())) {
  AgentTurnResults.withResultCollection(events);
  var iterator = events.stream().iterator();
  while (iterator.hasNext()) {
    var event = iterator.next();
    System.out.println(json.writeValueAsString(event));
  }
  var result = AgentTurnResults.getFinalResult(events);
  System.out.println(result.outputText());
  String sessionId = result.sessionId();
  System.out.println(sessionId);
}

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

client = OpenAI::Client.new
events = client.beta.agents.sessions.create_streaming(
  agent: {
    model: "gpt-6-astra",
    instructions: "Write clean code, run it, and report the actual output."
  },
  environment: { type: "openai_hosted" },
  input: "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output."
)
begin
  events.with_result_collection
  events.each do |event|
    puts JSON.generate(event.to_h)
  end
  result = events.get_final_result
  puts result.output_text
  session_id = result.session_id
  puts "Session: #{session_id}"
ensure
  events.close
end

1
2
3
4
5
6
7
8
9
10
11
12
13curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted" },
    "input": "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
    "stream": true
  }'

session_id をアプリケーションの会話状態とともに保存します。この ID を使って、その会話に追加のメッセージを送信したり、保存済みの作業内容を取得したりできます。

アクションの承認リクエストの自動レビューを有効にするには、自動レビューが有効なプロジェクトで対象のセッションを作成する際に、review を "auto_review" に設定します。この設定は、メインタスクが待機中で、入力の送信処理が完了しているときに変更できます。レビューモード、実行環境の前提条件、承認の仕組みについては「自動レビュー」を参照してください。

再利用可能なエージェント設定については「エージェントの設定」、環境の選択肢については「アーキテクチャ」を参照してください。environment.type: "none" のセッションでは、作成時に入力が必要です。リクエストのフィールド一覧はセッション作成の API リファレンスを参照してください。

セッションで Files API の添付ファイルを使用している場合、ファイルの確認時に HTTP 429 とエラーコード files_api_rate_limit_exceeded が返されることがあります。復旧手順は「Files API のレート制限」を参照してください。

入力サイズ

エージェントのランタイムが受け付けるリクエストの上限は 4 MiB（4,194,304 バイト）です。input と出力スキーマ（agent.text.format.schema）の合計サイズは、この上限を下回るようにしてください。Agents API が追加するメタデータの分も余裕を持たせてください。環境にアップロードするファイルには、別途ファイルの上限が適用されます。

進捗の確認と結果に応じた処理

エージェントの作業中は、イベントを通じて出力や状態の変化が通知されます。ターンが完了、失敗、キャンセルのいずれで終了したかを確認してください。セッションが待機中というだけでは、ターンが成功したかどうかは判断できません。

agent.session.turn.completed、agent.session.turn.failed、agent.session.turn.cancelled のいずれが届いたかを確認します。ターンが完了しても、すべてのツールの実行が成功したとは限らないため、エージェントの出力も確認してください。

セッションで関数の実行結果や環境への接続が必要な場合は、セッションを取得して required_actions を確認します。作業を続けるには、アプリケーションのコードで関数呼び出しを処理するか、環境に接続する必要があります。

イベントの種類とペイロードについては「イベントとアイテム」を参照してください。

作業の継続と追加指示

同じセッションにもう一度 agent.session.input.message を送信します。エージェントが作業中であれば、メッセージは実行中のターンへの追加指示になります。セッションが待機中であれば、これまでの会話を引き継いで新しいターンが始まります。

追加のメッセージにも同じ入力サイズの上限が適用されます。

保存済みのエージェントを更新すると、その変更は新しいセッションにのみ適用されます。このセッションの以降のターンでモデル、推論強度、サービスティアを変更するには、セッションの設定を更新してください。

入力の送信には、その会話のセッション ID を使います。アプリケーションがターン開始直後のイベントを受け取れるよう、メッセージを送信する前に、そのセッションのイベントストリームを購読してください。

メッセージの論理的な送信操作ごとに、冪等性キーを 1 つ作成します。入力を送信する前に、キーをメッセージとともに保存します。メッセージの送信には、保存したキーを使います。

追加メッセージの送信

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22// Reuse the same submission key when retrying this message.
async function sendMessage(client, sessionId, text, submissionKey) {
  await client.beta.agents.sessions.events.create(sessionId, {
    "Idempotency-Key": submissionKey,
    events: [
      {
        type: "agent.session.input.message",
        input: [
          {
            role: "user",
            content: [
              {
                type: "input_text",
                text,
              },
            ],
          },
        ],
      },
    ],
  });
}

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
31from uuid import uuid4


# Reuse the same submission key when retrying this message.
def send_message(
    client: OpenAI, session_id: str, text: str, submission_key: str
) -> None:
    client.beta.agents.sessions.events.create(
        session_id,
        idempotency_key=submission_key,
        events=[
            {
                "type": "agent.session.input.message",
                "input": [
                    {
                        "role": "user",
                        "content": [
                            {
                                "type": "input_text",
                                "text": text,
                            }
                        ],
                    }
                ],
            }
        ],
    )


submission_key = str(uuid4())
# Save this key with the message before submitting it.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23// Reuse the same submission key when retrying this message.
func sendMessage(ctx context.Context, client *openai.Client, sessionID, text, submissionKey string) error {
	return client.Beta.Agents.Sessions.Events.New(ctx,
		sessionID,
		openai.BetaAgentSessionEventNewParams{
			IdempotencyKey: openai.String(submissionKey),
			Events: []openai.AgentSessionInputParamUnion{
				{
					OfParamAgentSessionInputMessage: &openai.AgentSessionInputParamAgentSessionInputMessage{
						Input: []openai.AgentSessionInputMessageParam{
							{
								Content: []openai.InputContentParamUnion{
									{
										OfParamInputText: &openai.InputContentParamInputText{Text: text},
									},
								},
							},
						},
					},
				},
			},
		})
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// Reuse the same submission key when retrying this message.
public static void sendMessage(
    OpenAIClient client, String sessionId, String text, String submissionKey) {
  client
      .beta()
      .agents()
      .sessions()
      .events()
      .create(
          EventCreateParams.builder()
              .sessionId(sessionId)
              .idempotencyKey(submissionKey)
              .addEvent(
                  AgentSessionInputParam.AgentSessionInputMessage.builder()
                      .addInput(
                          AgentSessionInputMessageParam.builder()
                              .addInputTextContent(text)
                              .build())
                      .build())
              .build());
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# Reuse the same submission key when retrying this message.
def send_message(client, session_id, text, submission_key)
  client.beta.agents.sessions.events.create(
    session_id,
    idempotency_key: submission_key,
    events: [
      {
        type: "agent.session.input.message",
        input: [
          {
            role: "user",
            content: [
              {
                type: "input_text",
                text: text
              }
            ]
          }
        ]
      }
    ]
  )
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24curl \
  "https://api.openai.com/v1/agents/sessions/$session_id/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Idempotency-Key: $submission_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "agent.session.input.message",
        "input": [
          {
            "role": "user",
            "content": [
              {
                "type": "input_text",
                "text": "List the files in the current directory."
              }
            ]
          }
        ]
      }
    ]
  }'

キーは Idempotency-Key ヘッダーに指定し、自動再試行でも同じキーを使います。タイムアウトや応答の消失後にアプリケーションが再試行する場合は、同じキー、セッション ID、メッセージを使ってください。メッセージの本文が同じでも、別の送信操作には新しいキーを生成してください。

送信とストリーミングを組み合わせた例は「イベントとアイテム」を参照してください。

保存済みの作業内容の取得

イベントでは進捗をリアルタイムで確認できます。アイテムにはメッセージやツール呼び出しが保存され、完了した応答も含まれます。以前の作業内容を表示したり、ターンの終了後に結果を確認したりするには、次のようにアイテムを取得します。

セッションのアイテムの取得

Python

1
2
3
4
5
6
7// Pass your saved session ID to this helper.
async function listItems(client, sessionId) {
  return client.beta.agents.sessions.items.list(sessionId, {
    order: "asc",
    limit: 100,
  });
}

1
2
3# Pass your saved session ID to this helper.
def list_items(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.items.list(session_id, order="asc", limit=100)

1
2
3
4
5
6
7
8
9// Pass your saved session ID to this helper.
func listItems(ctx context.Context, client *openai.Client, sessionID string) (*pagination.CursorPage[openai.AgentSessionItemUnion], error) {
	return client.Beta.Agents.Sessions.Items.List(ctx,
		sessionID,
		openai.BetaAgentSessionItemListParams{
			Order: "asc",
			Limit: openai.Int(100),
		})
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14// Pass your saved session ID to this helper.
public static ItemListPage listItems(OpenAIClient client, String sessionId) {
  return client
      .beta()
      .agents()
      .sessions()
      .items()
      .list(
          ItemListParams.builder()
              .sessionId(sessionId)
              .order(ItemListParams.Order.of("asc"))
              .limit(100L)
              .build());
}

1
2
3
4
5
6
7
8# Pass your saved session ID to this helper.
def list_items(client, session_id)
  client.beta.agents.sessions.items.list(
    session_id,
    order: "asc",
    limit: 100
  )
end

1
2
3
4curl \
  "https://api.openai.com/v1/agents/sessions/$session_id/items?order=asc&limit=100" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

セッションの状態やターンの結果を確認する方法は「セッションの管理」を参照してください。ファイルの取得方法は「ファイルと成果物」を参照してください。

ストリームでは、受信できなかったイベントは再送されません。接続が切れた場合は、セッションとそこに保存されたアイテムを取得して、作業内容を復元してください。再接続の手順は「切断されたストリームの復旧」を参照してください。

実行中のターンのキャンセル

エージェントの作業を停止するには、実行中のターンをキャンセルします。キャンセル後も、セッションとそれまでの作業内容は引き続き利用できます。

実行中のターンのキャンセル

Python

1
2
3
4
5
6// Pass your saved session ID to this helper.
async function cancelTurn(client, sessionId) {
  await client.beta.agents.sessions.events.create(sessionId, {
    events: [{ type: "agent.session.input.cancel" }],
  });
}

1
2
3
4
5# Pass your saved session ID to this helper.
def cancel_turn(client: OpenAI, session_id: str) -> None:
    client.beta.agents.sessions.events.create(
        session_id, events=[{"type": "agent.session.input.cancel"}]
    )

1
2
3
4
5
6
7
8
9
10// Pass your saved session ID to this helper.
func cancelTurn(ctx context.Context, client *openai.Client, sessionID string) error {
	return client.Beta.Agents.Sessions.Events.New(ctx,
		sessionID,
		openai.BetaAgentSessionEventNewParams{
			Events: []openai.AgentSessionInputParamUnion{
				{OfParamAgentSessionInputCancel: &openai.AgentSessionInputParamAgentSessionInputCancel{}},
			},
		})
}

1
2
3
4
5
6
7
8
9
10
11
12
13// Pass your saved session ID to this helper.
public static void cancelTurn(OpenAIClient client, String sessionId) {
  client
      .beta()
      .agents()
      .sessions()
      .events()
      .create(
          EventCreateParams.builder()
              .sessionId(sessionId)
              .addEventAgentSessionInputCancel()
              .build());
}

1
2
3
4
5
6
7# Pass your saved session ID to this helper.
def cancel_turn(client, session_id)
  client.beta.agents.sessions.events.create(
    session_id,
    events: [{ type: "agent.session.input.cancel" }]
  )
end

1
2
3
4
5curl "https://api.openai.com/v1/agents/sessions/$session_id/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"type":"agent.session.input.cancel"}]}'

おすすめ

はじめに

基本概念

SDK と CLI

クラウドプロバイダー

リソース

レガシー API

モデルの選び方

テキストとコード

プロンプトの書き方

推論

画像

リアルタイム処理とオーディオ

特化型モデル

Agents API

Agents SDK

ChatKit

検索と情報取得

ツールとデータの接続

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

コンピューターとコード

メディア

GPT-Live

Realtime API

音声を使った開発

接続

音声処理

本番稼働の開始

パフォーマンスと品質

評価

コストとスループット

安全性とガバナンス

インフラとアクセス

業務運営

基本概念

計画

開発

テストと公開

コンバージョン仕様

ガイド

リソース

アイデンティティ

ChatGPT プランの利用状況

ガイド

ファイルのアップロード

API

効果測定

広告主向け API

API リファレンス

はじめに

はじめに

基礎

探す

対応プラットフォーム

リリース

ワークフロー

できること

Sites

dot

ChatGPT Space

リファレンス

カスタマイズ

設定ファイル

エージェントの設定

ChatGPT と Codex の機能拡張

Linux

Windows

開発ワークフロー

機能拡張と自動化

環境

Codex Cloud

Codex を使った開発

サードパーティ連携

リファレンス

権限

Codex Security

サイバー安全対策

はじめに

機能設定

ID とアクセス管理