OpenAI 运行与继续会话

会话持续保存智能体配置、对话和已完成工作。复用同一会话ID，即可发送后续消息继续任务。

会话与轮次

轮次是会话中的一次工作循环。向空闲会话发消息会启动新轮次；向活动轮次发消息则引导当前轮次。

轮次异步运行，应用可通过流式事件跟进，或通过Webhook接收状态变化。

需要未来或周期性启动时，可使用定时自动化，选择每次新建会话或继续已有对话。

开始工作

创建会话时提供智能体配置和初始 input，将 stream 设为 true，在同一请求中接收首轮事件。

按前置条件配置密钥和SDK后，可运行以下示例。OpenAI管理执行环境：

来源示例 1（javascript）：

程序文字说明15：编写清晰代码，运行并报告实际输出。

程序文字说明34：创建tree.py，使其打印当前目录文件的易读树状结构，运行并展示输出。

程序文字说明35：此拼接输入要求创建、运行tree.py目录树脚本并展示实际输出。

// [中文] 示例 1：开始工作。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import 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();
}

来源示例 2（python）：

沿用程序文字说明15。

沿用程序文字说明34。

沿用程序文字说明35。

## [中文] 示例 2：开始工作。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
from 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

来源示例 3（go）：

沿用程序文字说明15。

沿用程序文字说明34。

沿用程序文字说明35。

// [中文] 示例 3：开始工作。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import (
    "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)

来源示例 4（java）：

沿用程序文字说明15。

沿用程序文字说明35。

// [中文] 示例 4：开始工作。
// [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
import 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);
}

来源示例 5（ruby）：

沿用程序文字说明15。

沿用程序文字说明34。

沿用程序文字说明35。

## [中文] 示例 5：开始工作。
## [中文] 创建会话，保存返回会话 ID；设置 stream 时继续读取事件，创建请求本身不保证任务成功。
require "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

来源示例 6（bash）：

沿用程序文字说明15。

沿用程序文字说明34。

沿用程序文字说明35。

## [中文] 示例 6：开始工作。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions；示例占位地址需替换为实际资源。
curl --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 与应用对话状态一起保存，后续发送消息或读取工作都用它。

可复用设置见智能体配置，环境选择见架构。environment.type: "none" 的会话必须有初始输入，请求字段见创建会话参考。

Files API附件检查可能返回HTTP 429与 files_api_rate_limit_exceeded，恢复方法见文件速率限制。

输入大小

运行时接受最大4 MiB（4,194,304字节）的请求。input 与输出结构 agent.text.format.schema 合计应小于该值，并为API添加的元数据留空间。上传到环境的文件采用单独文件限制。

启用自动操作审查时，在已启用该功能的项目中创建符合条件的会话，并将 review 设为 "auto_review"。主任务空闲且输入提交处理已完成后，可更改该设置。审查模式、环境前置条件及批准行为详见自动审查。

跟踪进度并处理结果

事件报告输出和变化。判断轮次结果应看完成、失败或取消，不能只看空闲。

监听 agent.session.turn.completed、agent.session.turn.failed、agent.session.turn.cancelled，同时检查智能体输出：轮次完成不保证每个工具都成功。

需要函数结果或环境连接时，读取会话 required_actions，由应用处理函数调用或连接环境，工作才能继续。

类型和载荷见事件与项目。

继续或引导工作

向同一会话发送 agent.session.input.message。智能体正在工作则引导活动轮次；空闲则沿用对话启动新轮次。后续消息仍受输入大小限制。

更新已保存智能体只影响新会话。要为此会话后续轮次改变模型、推理强度或服务层级，需更新会话设置。

发送前先订阅会话事件流，避免遗漏早期事件。

每条逻辑提交生成一个幂等键，在发送前与消息一起保存，提交时使用此键：

来源示例 7（javascript）：

// [中文] 示例 7：继续或引导工作。
// [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
// [中文] 同一逻辑输入的重试复用原幂等键；新的逻辑提交使用新键。
// 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,
              },
            ],
          },
        ],
      },
    ],
  });
}

来源示例 8（python）：

## [中文] 示例 8：继续或引导工作。
## [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
## [中文] 同一逻辑输入的重试复用原幂等键；新的逻辑提交使用新键。
from 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.

来源示例 9（go）：

// [中文] 示例 9：继续或引导工作。
// [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
// 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},
                                    },
                                },
                            },
                        },
                    },
                },
            },
        })
}

来源示例 10（java）：

// [中文] 示例 10：继续或引导工作。
// [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
// [中文] 同一逻辑输入的重试复用原幂等键；新的逻辑提交使用新键。
// 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());
}

来源示例 11（ruby）：

## [中文] 示例 11：继续或引导工作。
## [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
## [中文] 同一逻辑输入的重试复用原幂等键；新的逻辑提交使用新键。
## 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

来源示例 12（bash）：

程序文字说明16：列出当前目录的文件。

## [中文] 示例 12：继续或引导工作。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions/$session_id/events；示例占位地址需替换为实际资源。
## [中文] 同一逻辑输入的重试复用原幂等键；新的逻辑提交使用新键。
curl \
  "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、消息重试。不同逻辑提交使用不同键，即使消息文字相同。

组合发送与流式示例见事件与项目。

读取已保存工作

事件显示实时进度，项目保存消息和工具调用，包括完成响应。读取项目可展示历史或检查轮次结束后的结果：

来源示例 13（javascript）：

// [中文] 示例 13：读取已保存工作。
// [中文] 读取已保存会话项目；它用于恢复历史，不是实时事件重放。
// 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,
  });
}

来源示例 14（python）：

## [中文] 示例 14：读取已保存工作。
## [中文] 读取已保存会话项目；它用于恢复历史，不是实时事件重放。
## 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)

来源示例 15（go）：

// [中文] 示例 15：读取已保存工作。
// [中文] 读取已保存会话项目；它用于恢复历史，不是实时事件重放。
// 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),
        })
}

来源示例 16（java）：

// [中文] 示例 16：读取已保存工作。
// [中文] 读取已保存会话项目；它用于恢复历史，不是实时事件重放。
// 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());
}

来源示例 17（ruby）：

## [中文] 示例 17：读取已保存工作。
## [中文] 读取已保存会话项目；它用于恢复历史，不是实时事件重放。
## 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

来源示例 18（bash）：

## [中文] 示例 18：读取已保存工作。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions/$session_id/items?order=asc&limit=100；示例占位地址需替换为实际资源。
curl \
  "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"

状态和轮次结果见管理会话，文件通过文件与产物取回。

流不会重放遗漏事件。断连后读取会话和已保存项目恢复工作，步骤见恢复断开的流。

取消活动轮次

想让智能体停止时取消当前轮次，会话和既往工作仍保留：

来源示例 19（javascript）：

// [中文] 示例 19：取消活动轮次。
// [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
// 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" }],
  });
}

来源示例 20（python）：

## [中文] 示例 20：取消活动轮次。
## [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
## 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"}]
    )

来源示例 21（go）：

// [中文] 示例 21：取消活动轮次。
// [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
// 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{}},
            },
        })
}

来源示例 22（java）：

// [中文] 示例 22：取消活动轮次。
// [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
// 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());
}

来源示例 23（ruby）：

## [中文] 示例 23：取消活动轮次。
## [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
## 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

来源示例 24（bash）：

## [中文] 示例 24：取消活动轮次。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions/$session_id/events；示例占位地址需替换为实际资源。
curl "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"}]}'