千问办公企业旗舰版开发者文档:创建会话与首轮任务。
认证方式见APP开发者文档 → 认证接入。
JSON请求体必填。
在
将花括号及其中的占位符替换为接口返回值。调用名取自「查询技能列表」或「查询专家套件列表」的
媒体类型:
创建会话绑定当前IAM用户;资源读取与变更按用户归属校验。写入发生超时或响应丢失时,不应假定服务端未接纳并盲目重复请求。
- 模块:会话服务(session)
- 接口:POST
/api/openapi/app/v1/sessions
请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| 无独立参数 | — | — | — | IAM用户凭据仍需由入口验证 |
请求体
JSON请求体必填。
请求 CreateSessionRequest
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| client_hint | string | 否 | maxLength=32 | 调用端的可选统计标记;建议省略。 |
| initial_prompt | InitialPrompt | 是 | — | 要执行的首轮任务,必填。运行环境准备完成后自动开始,无需另发一次 Prompt。 |
| locale | string | 否 | BCP 47 语言标签 | BCP 47 语言标签,用于指定 Agent 的回复语言。 |
| mode | string | 否 | 必须为当前账户可用档位;没有默认档位时必填 | 能力档位,例如 pro、flash。省略时使用账户默认档位;若无默认档位则必填。可用值按账户解析,不可用值返回 422 并说明允许的取值。 |
| multi_agent | MultiAgentConfig | 否 | — | 是否允许创建子会话,以及子会话使用的档位。每个子会话使用独立运行环境,会增加计算资源消耗。 |
| name | string | 否 | — | 显示名称。省略时根据 Prompt 生成;显式指定后服务端不再自动改名,因此不会产生自动命名的 session_name 通知。 |
| parent_session_id | string | 否 | 嵌套最多 3 层;每个父会话最多 15 个直接子会话 | 指定父会话;嵌套最多 3 层,每个父会话最多 15 个直接子会话,超出返回 422。 |
| timezone | string | 否 | IANA 时区名称 | IANA 时区名称,供 Agent 处理日期和时间。 |
| ttl_seconds | integer | 否 | minimum=60;maximum=86400;format="int64" | 会话最长存活时间,单位秒,范围 60~86400,默认 3600;到期以 end_reason=timeout 结束。 |
请求 InitialPrompt
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| files | array<PromptFile> | 否 | maxItems=50 | 附件列表,最多 50 个;文件必须已存储,本接口不负责上传。 |
| text | string | 是 | minLength=1;maxLength=100000 | 提交给 Agent 的指令文本,长度 1~100000 个字符。 |
在首轮任务中选择技能或专家套件
在 initial_prompt.text 中填写选择标记,后接一个空格和任务文本。资源详情中的 capabilities.can_use 为 true 表示当前用户有资格使用该资源且已启用。
| 资源 | initial_prompt.text 格式 |
|---|---|
| 技能 | @[skill:{name}] 任务文本 |
| 专家套件 | @[plugin:{name}:{显示名称}] 任务文本 |
items[].name,也可直接取对应详情的 name。保留原始大小写和连字符。专家套件的显示名称取同一条目的 name_cn,为空时取 name_en,两者均为空时取 name。
对于企业自建资源,APP 的 name 对应管理后台创建技能或专家套件时填写的唯一标识 name。技能的 name_cn、name_en 分别对应后台同名字段。专家套件的 name_cn、name_en 分别对应后台的 display_name_cn、display_name。
请求 PromptFile
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| path | string | 是 | minLength=1 | 已有文件的存储路径,例如上传文件或之前的会话产物;不得包含 ..,仅可访问当前账户有权使用的文件。 |
请求 MultiAgentConfig
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| child_mode | string | 否 | — | 指定子会话的能力档位;省略时继承当前会话档位。 |
| enabled | boolean / null | 是 | — | 是否允许 Agent 创建子会话。每个子会话使用独立运行环境,会增加计算资源消耗;已创建的子会话列在会话详情的 children 中。 |
响应
| HTTP | 说明 |
|---|---|
| 202 | 已接收请求 |
| default | 错误响应。按 code 判断具体错误,不能仅依赖 HTTP 状态码,多种错误可能共用状态码。 |
application/json。
响应202 CreateSessionResponse
| 字段 | 类型 | 必填 | 约束 | 契约说明 |
|---|---|---|---|---|
| created_at | string | 是 | ISO 8601 时间字符串 | 会话创建时间,ISO 8601,含微秒和时区。 |
| first_turn_id | string | 否 | — | 首轮 Prompt 对应的回合 ID,开始执行前即可返回,用于筛选事件或查询回合详情。内部未携带首轮 Prompt 的路径可能省略;当前创建接口要求 initial_prompt。此 ID 不保证派发成功,失败时详情可能持续返回 404;应结合会话状态排查,不无限等待此回合。 |
| session_id | string | 是 | — | 新建会话 ID,供后续相关接口使用。 |
| status | string | 是 | — | starting 表示运行环境仍在准备。查询会话详情直到状态发生变化,不要只等待 idle:带首轮 Prompt 的会话可能从 starting 直接进入 running。首轮任务自动执行,无需重复发送 Prompt。 |