OpenAI 管理会话

将每个会话ID与应用数据一起保存，用于读取当前状态、处理智能体请求及删除会话。

查找会话

列出项目内会话，浏览既往工作；SDK分页辅助功能可以继续获取页面：

来源示例 1（javascript）：

// [中文] 示例 1：查找会话。
// [中文] 列出当前项目的会话；需要更多结果时继续分页，不把一页当作全部。
import OpenAI from "openai";

const client = new OpenAI();
let page = await client.beta.agents.sessions.list({ limit: 20 });
console.log(page.data);
if (page.hasNextPage()) {
  page = await page.getNextPage();
  console.log(page.data);
}

来源示例 2（python）：

## [中文] 示例 2：查找会话。
## [中文] 列出当前项目的会话；需要更多结果时继续分页，不把一页当作全部。
from openai import OpenAI

client = OpenAI()
page = client.beta.agents.sessions.list(limit=20)
print(page.to_json())
if page.has_next_page():
    page = page.get_next_page()
    print(page.to_json())

来源示例 3（go）：

// [中文] 示例 3：查找会话。
// [中文] 列出当前项目的会话；需要更多结果时继续分页，不把一页当作全部。
import (
    "context"
    "fmt"

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

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.List(ctx,
    openai.BetaAgentSessionListParams{Limit: openai.Int(20)})
if err != nil {
    panic(err)
}
fmt.Println(result.Data)
if result.HasMore {
    result, err = result.GetNextPage()
    if err != nil {
        panic(err)
    }
    fmt.Println(result.Data)
}

来源示例 4（java）：

// [中文] 示例 4：查找会话。
// [中文] 列出当前项目的会话；需要更多结果时继续分页，不把一页当作全部。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionListParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client.beta().agents().sessions().list(SessionListParams.builder().limit(20L).build());
System.out.println(result.items());
if (result.hasNextPage()) {
  result = result.nextPage();
  System.out.println(result.items());
}

来源示例 5（ruby）：

## [中文] 示例 5：查找会话。
## [中文] 列出当前项目的会话；需要更多结果时继续分页，不把一页当作全部。
require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.list(limit: 20)
puts result.data
if result.next_page?
  result = result.next_page
  puts result.data
end

来源示例 6（bash）：

## [中文] 示例 6：查找会话。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions?limit=20&order=desc、https://api.openai.com/v1/agents/sessions；示例占位地址需替换为实际资源。
## [中文] 有后续页时将当前 last_id 作为下一页 after；会话列表和追踪列表游标不能混用。
page=$(curl -sS --fail-with-body "https://api.openai.com/v1/agents/sessions?limit=20&order=desc" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY")
after=$(printf '%s' "$page" | jq -r 'select(.has_more) | .last_id // empty')

if [ -n "$after" ]; then
  curl --get "https://api.openai.com/v1/agents/sessions" \
    -H "OpenAI-Beta: agents=v1" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    --data-urlencode "after=$after" \
    --data-urlencode "limit=20"
fi

检查会话

传入API客户端和对话会话ID，读取状态、智能体配置、环境及 required_actions：

来源示例 7（javascript）：

// [中文] 示例 7：检查会话。
// [中文] 读取当前会话状态和 required_actions；历史项目不代表动作仍待处理。
// Pass your saved session ID to this helper.
async function retrieveSession(client, sessionId) {
  return client.beta.agents.sessions.retrieve(sessionId);
}

来源示例 8（python）：

## [中文] 示例 8：检查会话。
## [中文] 读取当前会话状态和 required_actions；历史项目不代表动作仍待处理。
## Pass your saved session ID to this helper.
def retrieve_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.retrieve(session_id)

来源示例 9（go）：

// [中文] 示例 9：检查会话。
// [中文] 读取当前会话状态和 required_actions；历史项目不代表动作仍待处理。
// Pass your saved session ID to this helper.
func retrieveSession(ctx context.Context, client *openai.Client, sessionID string) (*openai.AgentSession, error) {
    return client.Beta.Agents.Sessions.Get(ctx, sessionID)
}

来源示例 10（java）：

// [中文] 示例 10：检查会话。
// [中文] 读取当前会话状态和 required_actions；历史项目不代表动作仍待处理。
// Pass your saved session ID to this helper.
public static AgentSession retrieveSession(OpenAIClient client, String sessionId) {
  return client
      .beta()
      .agents()
      .sessions()
      .retrieve(SessionRetrieveParams.builder().sessionId(sessionId).build());
}

来源示例 11（ruby）：

## [中文] 示例 11：检查会话。
## [中文] 读取当前会话状态和 required_actions；历史项目不代表动作仍待处理。
## Pass your saved session ID to this helper.
def retrieve_session(client, session_id)
  client.beta.agents.sessions.retrieve(session_id)
end

来源示例 12（bash）：

## [中文] 示例 12：检查会话。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions/$session_id；示例占位地址需替换为实际资源。
curl \
  "https://api.openai.com/v1/agents/sessions/$session_id" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

完整结构见读取会话参考。

处理所需动作

requires_action 表示应用必须先行动，工作才能继续。收到 agent.session.requires_action 后，重新读取会话，检查 required_actions：

• function_call：用 arguments 执行 name 标识的函数，在同一会话用动作的 turn_id 与 call_id 返回结果，见函数工具。
• environment_connection：连接 environment_id 标识的环境，见连接环境。

事件告诉应用何时检查，当前会话告诉应用做什么。重启或流断连后，重新读取会话找待处理动作，处理完继续跟随事件直到轮次结果。

消息、工具调用及轮次结果见读取项目与轮次，命令执行归属见观察委派。浏览器访问和认证等其他所需动作，按对应计算机使用指南处理。

删除会话

应用不再需要时删除，API中会话被移除，物理清理可能继续异步执行：

来源示例 13（javascript）：

// [中文] 示例 13：删除会话。
// [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";

async function deleteSession(client, sessionId) {
  return client.beta.agents.sessions.delete(sessionId);
}

const result = await deleteSession(new OpenAI(), "sess_123");
console.log(result);

来源示例 14（python）：

## [中文] 示例 14：删除会话。
## [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
## Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI


def delete_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.delete(session_id)


if __name__ == "__main__":
    result = delete_session(OpenAI(), "sess_123")
    print(result.to_json())

来源示例 15（go）：

// [中文] 示例 15：删除会话。
// [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
// Replace the illustrative IDs and URLs below with your own resource values.
package main

import (
    "context"
    "fmt"

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

func deleteSession(ctx context.Context, client *openai.Client, sessionID string) (*openai.AgentSessionDeleted, error) {
    return client.Beta.Agents.Sessions.Delete(ctx, sessionID)
}

func main() {
    client := openai.NewClient()
    result, err := deleteSession(context.Background(), &client, "sess_123")
    if err != nil {
        panic(err)
    }
    fmt.Println(result)
}

来源示例 16（java）：

// [中文] 示例 16：删除会话。
// [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
// 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.AgentSessionDeleted;
import com.openai.models.beta.agents.sessions.SessionDeleteParams;

public final class AgentsApiSessionsDeleteSessionExample {
  public static AgentSessionDeleted deleteSession(OpenAIClient client, String sessionId) {
    return client
        .beta()
        .agents()
        .sessions()
        .delete(SessionDeleteParams.builder().sessionId(sessionId).build());
  }

  public static void main(String[] args) {
    var result = deleteSession(OpenAIOkHttpClient.fromEnv(), "sess_123");
    System.out.println(result);
  }
}

来源示例 17（ruby）：

## [中文] 示例 17：删除会话。
## [中文] 删除指定会话；自托管提供商计算资源还需独立清理。
## Replace the illustrative IDs and URLs below with your own resource values.
require "openai"

def delete_session(client, session_id)
  client.beta.agents.sessions.delete(session_id)
end

puts delete_session(OpenAI::Client.new, "sess_123")

来源示例 18（bash）：

## [中文] 示例 18：删除会话。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions/$session_id；示例占位地址需替换为实际资源。
curl -X DELETE \
  "https://api.openai.com/v1/agents/sessions/$session_id" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

只想停止当前工作而保留对话时，取消活动轮次。删除响应见删除会话参考。