Skip to main content

获取 Session

根据 Session ID 返回会话状态、Agent 快照、环境摘要与 Token 用量。

接口

GET /agents/sessions/{session_id} 成功返回 200 和完整 Session 对象。

路径参数

session_id string (必选)Session ID,按不透明字符串使用本接口没有 Query 参数。session_id 格式错误、不存在、已归档或属于其他工作空间时返回 404。

请求示例

curl -sS "$BASE_URL/agents/sessions/sess_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

响应字段

字段不齐时为 null。 status=idle 或 HTTP 200 不充分证明上一轮 Turn 成功;需要结合 Turn 终态判断。usage 要求相关计数齐全,否则整个字段为 null。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已消耗额度,单位为美分

响应示例

{
  "id": "sess_xxx",
  "object": "agent.session",
  "created_at": 1794118835,
  "last_active_at": 1794118900,
  "status": "idle",
  "agent": {
    "id": "agent_xxx",
    "model": "qwen3.8-max",
    "instructions": "回答简洁。",
    "reasoning": {"effort": "none", "summary": "auto"},
    "text": {"format": {"type": "text"}, "verbosity": "medium"},
    "tools": [],
    "multi_agent": {"enabled": false, "max_concurrent_subagents": null},
    "name": null
  },
  "environment": {"type": "none"},
  "metadata": {},
  "required_actions": [],
  "vault_ids": [],
  "error": null,
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 8,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 20
  }
}

错误码

业务错误返回 error 对象,包含 type、code、message 和 param。常见错误如下:
HTTP 状态码错误类型 / 错误码解决方案
400invalid_request_error / invalid_request_error按路径参数格式传入有效值
401authentication_error / invalid_api_key在请求头携带有效的 Authorization: Bearer $DASHSCOPE_API_KEY
404not_found_error / not_found_error使用当前工作空间中未归档且格式正确的 Session ID
502server_error / agents_api_upstream_unavailable稍后重试;持续失败时提交工单并提供响应头中的 x-request-id