认证与空间
平台用户通过POST /api/auth/login 登录，请求体为 {"username":"...","password":"..."}，将返回的 token 放入 Authorization: Bearer TOKEN。管理 Agent、Team、Workflow 和 Application 时使用这个身份。应用后端则使用 Application 下签发的 X-API-Key，只能访问凭据明确授权的目标和操作。
空间请求使用 X-AgentScope-Tenant、X-AgentScope-Namespace。如果请求体或查询参数中也包含空间字段，它们必须一致。Runtime Host、Task/Attempt 和 Environment 的执行凭据只用于相应运行协议，不能拿来调用业务 Session API。
Application 与调用凭据
Application 保存调用方身份、成员和额度。创建凭据时需要显式给出targets 和 scopes，服务只返回一次完整的 apiKey；列表接口不会返回明文。应用凭据不会自动获得管理资源或替指定人员审批的权限。
凭据 scope 包括
invoke、read、interact、cancel 和 webhooks:write。Application 成员角色为 viewer、operator、approver。并发限制用于控制应用待处理的工作数量；tokenBudget 依据已报告用量限制后续调用，不是供应商的预付费硬额度。
Session 与 Turn API
以下路径以/api/v1/agent-sessions 为前缀。创建 Session 时，target.type 为 agent、team 或 workflow，target.id 为相应资源 ID。Agent 可指定 version，Workflow 可指定 revisionId。省略版本时，Service 在创建会话时解析并固定版本，后续 Turn 沿用该配置。
Managed Session 还可指定 environmentId、memoryStoreIds、vaultIds、agentOverrides 和 resources。通用参数包括 timeoutSeconds、budget.maxTokens、inputSchema、outputSchema 和 resultMapping；需要约束业务输入和输出时，应在创建 Session 时提供这些契约。
Managed Agent 的
/budget、/checkpoints、/fork、/inputs/inject、/subagents 与 /export 是同一套 API 的能力扩展。并非每个目标都支持这些操作，请按会话指南与 capabilities 使用。文件格式见文件与产物，事件与签名见 SSE。
统一 Agent 目录与运行绑定
以下接口使用平台身份；创建和列表的tenant、namespace 与请求头范围保持一致。Agent 的 id、agentKey 和展示名称不是同一个字段。创建/注册的操作示例见Agent 管理。
binding.kind 使用 managed、hosted-runtime 或 external-application。Managed 创建时由平台生成绑定配置；Hosted 配置使用 runtimeProfileId、runtimePoolId。External 使用独立注册流程，不通过普通创建接口直接伪造一个在线实例。
POST /api/v1/agent-registrations 接受 agentKey、instanceKey、范围、framework、routingKey、capabilities 等，返回 agent、binding、instance、registrationCredential。当前注册入口不校验调用身份，需由部署方限制受信任接入范围；返回注册凭据不代表首次注册已经通过身份认证。字段和实际传输接入见External 参数参考。
任务、编排、自动化与资源参数
以下参考覆盖创建、更新和反馈参数；各页同时给出 API 操作与返回值衔接，Console 操作另列在控制台模块。SDK 与可运行示例
Python 的ManagementClient 用于准备资源与凭据，ServiceClient 用于创建 Session、提交 Turn 和读取结果。前端 TypeScript 客户端位于 frontend/src/api/serviceSessions.ts。运行时注册和任务回报 SDK 则用于接入执行器，与应用调用客户端的职责不同。
service-controlplane/examples/service-api，可以分别对 Agent、Team 和 Workflow 创建 Session。HTTP 客户端不会替应用批准工具操作，也不会在网络失败时擅自创建新任务；应用应保存 Session ID、Turn ID 和幂等键，按服务 API处理恢复。
错误与版本冲突
遇到400 时先检查请求内容，401 表示凭据无效，403 表示当前身份没有相应权限。404 可能表示资源不存在，也可能表示当前身份无权访问，不应据此推断其他用户的数据。409 需要检查资源状态、版本或幂等请求是否改变；事件 410 则需要重新加载快照。限流和临时服务错误应退避重试，并保留同一个逻辑请求的幂等键。
管理资源更新前先读取当前版本。Issue 决策与 Workflow 发布使用 expectedVersion，Agent 定义等更新使用各自的 version 字段，不能自动用新版本重放已经过期的人工决定。
机器可读契约位于 agentscope-service/docs/service-api/openapi-v1.json，其中列出当前 Session API 和应用凭据路径。旧调用入口的迁移说明位于同目录的 session-api-migration.md。