Skip to main content

列出 Session

分页列出当前工作空间中的 Session,可按 Agent 过滤。

接口

GET /agents/sessions 成功返回 200 和列表信封,data 为 Session 对象数组。

查询参数

limit integer (可选)每页数量,默认 20,范围 1..100;空串或不在此范围返回 400order string (可选)排序方向,asc 或 desc,默认 desc;非法值返回 400after string (可选)资源 ID 游标,最多 256 字节且不能为空白;不包含游标项agent_id string (可选)Agent ID 过滤条件,按已保存或内联 Agent ID 过滤,显式空值非法,重复传入返回 400翻页时首次不传 after,后续传上一页的 last_id。列表按 (created_at, 资源 ID) 排序。before 等其他未知 Query 参数会被忽略,反向翻页请使用 order 和 after。列表可能有短暂延迟,可能暂时看不到刚创建的 Session;需要确认最新状态时使用获取 Session。列表不提供全局快照或立即可见性保证。

请求示例

curl -sS "$BASE_URL/agents/sessions?limit=20&order=desc&agent_id=agent_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

响应字段

object string列表对象类型,固定为 listdata array当页 Session 对象,空时为 []first_id string / null当页首项 ID。空页为 nulllast_id string / null当页末项 ID。空页为 null,后续 after 使用该值has_more boolean当前检索方向是否还有下一页

Session 字段

id stringSession ID,继续对话时复用object stringSession 对象类型,固定为 agent.sessioncreated_at integer创建时间,Unix 秒last_active_at integer最近活动时间,Unix 秒;不是版本号或锁status stringSession 状态:idle、in_progress、requires_action、failedagent object当前生效的 Agent 快照。
id stringAgent ID;内联配置生成的是会话快照 ID,不是可复用的已保存 Agent,不能通过 Agent GET 查询model string模型 IDinstructions string / null自定义指令name string / null展示名称reasoning object / null推理配置,包含 effort、summarytext object / null文本输出配置;包含 format 和 verbositytools array工具配置multi_agent object / null子 Agent 配置;包含 enabled、max_concurrent_subagents
environment object环境安全摘要;type=none 时只有 type。
type string环境类型;none 或 openai_hostedid string环境 ID,无权威来源时省略status string环境状态:无权威来源时省略environment_template_id string环境模板 ID;无权威来源时省略workspace_directory string工作目录;无权威来源时省略error string / null环境错误说明;无权威来源时省略desktop object / null桌面配置;包含 enabledcapability_directories array<string> / null能力发现目录network object / null网络策略;包含 access、allowed_domainspackages object / null包列表;包含 npm、python、systemfiles array环境文件安全元数据skills arraySkill 安全元数据plugins array插件信息,当前托管环境为 []
metadata objectSession 元数据,空值为 {}vault_ids array<string>创建时记录的 Vault ID,不代表挂载已完成required_actions array需要客户端处理的 Function 调用;空时为 []。
type stringItem 类型,固定为 function_callturn_id string公开 Turn IDcall_id stringFunction 调用 IDname string函数名arguments object已解析的调用参数
error string / nullSession 级错误说明,与 Turn 的结构化 error 不同usage object / nullToken 用量。
input_tokens integer输入 Token 数input_tokens_details object输入 Token 明细。
cached_tokens integer命中缓存的输入 Token 数
output_tokens integer输出 Token 数output_tokens_details object输出 Token 明细。
reasoning_tokens integer推理 Token 数
total_tokens integer总 Token 数
spend_control object费用控制,仅历史记录带值时返回;创建和更新接口不接受写入。
limit integer额度上限,单位为美分consumed integer / null已消耗额度,单位为美分
字段不齐时为 null。

响应示例

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

错误码

业务错误返回 error 对象,包含 type、code、message 和 param。常见错误如下:
HTTP 状态码错误类型 / 错误码解决方案
400invalid_request_error / invalid_request_error按查询参数说明修正 limit、order、agent_id,并移除重复参数
401authentication_error / invalid_api_key在请求头携带有效的 Authorization: Bearer $DASHSCOPE_API_KEY
404not_found_error / not_found_error确认父资源存在且属于当前工作空间;使用本集合上一页返回的 last_id 作为 after
502server_error / agents_api_upstream_unavailable稍后重试;持续失败时提交工单并提供响应头中的 x-request-id