Skip to main content

创建会话与首轮任务

千问办公企业旗舰版开发者文档:创建会话与首轮任务。

认证方式见APP开发者文档 → 认证接入。
  • 模块:会话服务(session)
  • 接口:POST/api/openapi/app/v1/sessions

请求参数

参数位置类型必填说明
无独立参数———IAM用户凭据仍需由入口验证

请求体

JSON请求体必填。

请求 CreateSessionRequest

字段类型必填约束契约说明
client_hintstring否maxLength=32调用端的可选统计标记;建议省略。
initial_promptInitialPrompt是—要执行的首轮任务,必填。运行环境准备完成后自动开始,无需另发一次 Prompt。
localestring否BCP 47 语言标签BCP 47 语言标签,用于指定 Agent 的回复语言。
modestring否必须为当前账户可用档位;没有默认档位时必填能力档位,例如 pro、flash。省略时使用账户默认档位;若无默认档位则必填。可用值按账户解析,不可用值返回 422 并说明允许的取值。
multi_agentMultiAgentConfig否—是否允许创建子会话,以及子会话使用的档位。每个子会话使用独立运行环境,会增加计算资源消耗。
namestring否—显示名称。省略时根据 Prompt 生成;显式指定后服务端不再自动改名,因此不会产生自动命名的 session_name 通知。
parent_session_idstring否嵌套最多 3 层;每个父会话最多 15 个直接子会话指定父会话;嵌套最多 3 层,每个父会话最多 15 个直接子会话,超出返回 422。
timezonestring否IANA 时区名称IANA 时区名称,供 Agent 处理日期和时间。
ttl_secondsinteger否minimum=60;maximum=86400;format="int64"会话最长存活时间,单位秒,范围 60~86400,默认 3600;到期以 end_reason=timeout 结束。

请求 InitialPrompt

字段类型必填约束契约说明
filesarray<PromptFile>否maxItems=50附件列表,最多 50 个;文件必须已存储,本接口不负责上传。
textstring是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

字段类型必填约束契约说明
pathstring是minLength=1已有文件的存储路径,例如上传文件或之前的会话产物;不得包含 ..,仅可访问当前账户有权使用的文件。

请求 MultiAgentConfig

字段类型必填约束契约说明
child_modestring否—指定子会话的能力档位;省略时继承当前会话档位。
enabledboolean / null是—是否允许 Agent 创建子会话。每个子会话使用独立运行环境,会增加计算资源消耗;已创建的子会话列在会话详情的 children 中。

响应

HTTP说明
202已接收请求
default错误响应。按 code 判断具体错误,不能仅依赖 HTTP 状态码,多种错误可能共用状态码。
媒体类型:application/json。

响应202 CreateSessionResponse

字段类型必填约束契约说明
created_atstring是ISO 8601 时间字符串会话创建时间,ISO 8601,含微秒和时区。
first_turn_idstring否—首轮 Prompt 对应的回合 ID,开始执行前即可返回,用于筛选事件或查询回合详情。内部未携带首轮 Prompt 的路径可能省略;当前创建接口要求 initial_prompt。此 ID 不保证派发成功,失败时详情可能持续返回 404;应结合会话状态排查,不无限等待此回合。
session_idstring是—新建会话 ID,供后续相关接口使用。
statusstring是—starting 表示运行环境仍在准备。查询会话详情直到状态发生变化,不要只等待 idle:带首轮 Prompt 的会话可能从 starting 直接进入 running。首轮任务自动执行,无需重复发送 Prompt。

使用说明

创建会话绑定当前IAM用户;资源读取与变更按用户归属校验。写入发生超时或响应丢失时,不应假定服务端未接纳并盲目重复请求。