为应用准备调用凭据
在开发和调试阶段，可以使用登录得到的用户 Bearer token。接入业务后端时，建议创建 Application，为它签发独立的 API key，并明确授予它可以使用的 Agent、Team 或 Workflow。凭据属于 Application，因此同一应用更换 key 后仍能访问自己的 Session；其他应用即使使用同一个 Agent，也不能读取这些记录。API key 应保存在业务后端，由后端检查最终用户的业务权限。 下面的命令假定已经完成部署与登录，并创建了一个可以正常执行的 Managed Agent。请保留这些步骤中的BASE_URL、TOKEN、TENANT、NAMESPACE 和 AGENT_ID。创建 Application 和签发凭据属于管理操作，需要使用该 Application 所有者的用户身份。
invoke 允许提交工作，read 允许读取记录，interact 允许补充输入，cancel 允许取消；注册和管理回调还需要 webhooks:write。这些 scope 不会把应用变成人工审批人，指定人员的确认仍需由有权限的用户完成。
创建 Session，直接选择执行目标
下面的请求为资料助手创建 Session。Session 保存本次工作选择的配置和后续执行记录；创建成功并不代表已经提交了一项任务。建议对创建请求也提供稳定的幂等键，并保存返回的id，避免网络重试时建立重复会话。
target.type 可以是 agent、team 或 workflow。Agent 目标使用统一目录中的 ID，因此 Managed、External 和 Hosted 都使用 agent；它们的区别来自运行绑定。Team 使用 Team ID。Workflow 使用定义 ID，可以通过 revisionId 指定已发布版本；没有指定时，Service 选择当前最新的已发布版本。Workflow 的发布用于固定流程内容，与应用调用入口是两个不同的问题。
Session 创建时会固定目标配置及其依赖。Managed Agent 可以通过 target.version 选择定义版本。更新 Agent、Team 或 Workflow 后，新 Session 可以使用新配置，已有 Session 继续沿用自己的配置。Environment、Memory、Vault 等运行资源有各自的访问与更新规则；保存配置版本并不意味着外部业务数据永远不变。
如果 Agent 访问外部工具时需要使用特定凭据，应在创建 Session 时选择相应的 Vault，也可以继承 Agent 的默认 Vault。应用调用 Service 所使用的 API key 不会自动成为工具访问外部系统的凭据。配置方法和 vaultIds 的使用方式见在 Session 中选择 Vault。
提交一轮任务
向 Session 的/turns 提交请求就会创建一个 Turn。Managed Agent 支持文本 message，也支持由用户消息和内容块组成的 input。Team 和 Workflow 可以使用结构化业务 input，让平台将其交给协作或流程执行器；具体输入应与目标实际处理的内容一致。
202 Accepted，表示任务已经接收，执行可能仍在排队或进行中。网络超时后重试时，应使用同一个 Session、同一个幂等键和完全相同的请求内容。服务会返回原来的 Turn；如果沿用 key 却修改内容，则返回 409 Conflict。只有确实提交下一轮任务时，才应换一个新 key。
同一个 Session 中的 Turn 按顺序执行。Managed Agent 会保留会话上下文；Team 和 Workflow 的每个 Turn 会启动独立任务，历史记录集中保存在 Session 中，但不承诺把前一个任务的内部执行上下文直接传给下一次任务。需要沿用上次结果时，应用应在输入中明确提供所需资料。对于互不相关的对象或并行批次，通常应创建不同 Session。
恢复页面并观察执行
应用应保存业务对象、Session ID 和 Turn ID 的关联。用户刷新页面时，先读取 Session 的/snapshot 恢复已有内容，再从其中的 as_of 游标订阅 /events/stream。刷新只是在恢复显示，不应重新发送任务输入。如果页面仍保留之前的状态，则可以从最后已经成功处理的事件游标继续读取。
需要只观察某一轮任务时，可以使用 /turns/{turnId}/snapshot 和 /turns/{turnId}/events/stream。Session 游标与 Turn 游标分别属于各自的事件记录，不能交叉使用。Session 事件流会继续等待后续 Turn，因此连接关闭不表示业务完成。完成判断应读取对应 Turn 的 status：completed 表示成功，partial_succeeded 表示部分成功，failed、cancelled 和 timed_out 表示其他终态。
单轮快照中的 items、tools、required_actions、steps、artifacts 和 usage 按标识组织，便于应用更新界面。Managed Session 快照同时保留完整的会话消息、子 Agent 和原生交互记录。两种查看范围的具体数据格式见机器可读契约；事件续传和回调验证见事件与通知。
在执行中参与交互
Agent 需要用户确认、补充资料或提供外部工具结果时，应用从快照中的required_actions 读取待办，再向对应 Turn 的 /actions 提交答复。请求应包含待办的 request_id，需要版本校验的待办还应包含 expected_version。Managed Agent 的确认答复放在 payload 中，例如 {"allow":true}。涉及指定审批人的请求，应改用该用户的登录身份提交，应用 key 本身不能替他作出决定。
每种运行绑定能提供的交互不同。先读取 Session 的 /capabilities 了解目标支持范围，在显示取消、补充输入或恢复按钮前，再读取 Turn 的 /capabilities 中的 available_commands。取消请求被接受后，仍需继续观察状态，直到确认执行已经停止。需要进一步了解如何补充要求、回答待办或恢复执行时，可以继续阅读会话、任务与预算。
凭据、预算和后台通知
Application 的maxConcurrent 和 tokenBudget 约束该应用通过不同 key、不同 Session 提交的工作。Token 用量依据运行时报告累计，预算耗尽时会拒绝后续提交，因此它是执行治理能力，不是外部模型账单的实时硬上限。创建 Session 时，还可以设置 timeoutSeconds 和 budget.maxTokens，约束该 Session 中每个 Turn 的执行。Managed 会话自己的预算则通过 /budget 管理，具体配置与用量查询见用量、子 Agent 与预算。
后台应用可以为 Session 注册 Webhook，在任务完成、失败或等待交互时收到通知。回调可能重复投递，应用应验证签名、按事件 ID 去重，再读取 Session 或 Turn 确认最新状态。完整协议和重试方式见Webhook 后台通知。
检查交付结果
Turn 的completed 表示这轮执行成功结束。应用还需要检查实际交付是否符合业务要求，例如报告是否包含所需来源、文件是否能够下载，以及结构化结果是否包含后续处理所需的数据。返回的是文件时，应通过文件与产物中的接口读取实际产物，不能仅凭 Agent 回复中的文件名判断交付已经完成。
如果任务需要严格的业务输入和输出，可以在创建 Session 时提供 inputSchema、outputSchema 和 resultMapping。这些设置固定在当前 Session 的执行配置中。应先验证目标真实返回的数据，再设置输出映射和校验规则；Agent 在文字中写出 JSON，不等于平台已把这段文字转换为业务对象。这些规则用于检查数据格式，不能代替对内容质量的验收，也不会自动驱动 Agent 反复修改结果。
如果业务还需要保存负责人、讨论和人工验收记录，可以使用工作分派、审批与验收中的 Issue 来组织交付。Issue 的验收与 Session 中一次执行的完成是两个不同的判断：前者确认业务工作是否被接受，后者记录这轮执行是否结束。
使用 SDK 与可运行示例
PythonServiceClient 封装了相同的 Session API。下面的代码使用已经授予目标权限的应用 key；这里的 AGENT_ID 是平台 Agent ID。
agentscope-service/service-controlplane/examples/service-api 提供 Agent、Team 和 Workflow 的注册与调用示例。管理对象使用 ManagementClient，应用执行使用 ServiceClient。接口定义位于 agentscope-service/docs/service-api/openapi-v1.json。