games-development-ai/.claude/skills/agentscope-skill/references/studio-rest-api.md

AgentScope Studio / Agent Service REST API 参考（精炼版）

本文档是 AgentScope 2.0（OpenAPI info.version = 2.0.1，spec 路径 /v2/deploy/openapi.json，标题 AgentScope）托管式 Agent Service（Studio 后端）REST API 的精炼速查。源自 29 篇官方 API 原文，按资源域归并整理；YAML 已翻译为可读字段表，重复的脚手架已去重。

总览与全局约定

• 鉴权：所有端点（除明确说明外）均要求请求头 x-user-id（string，必填）——调用方用户 ID。这是临时的基于 header 的身份机制，未来将替换为 JWT。下文各端点不再重复列出该 header。
  • 例外：少数纯前端表单 schema 端点不要求 x-user-id（见下文 GET /agent/schema、GET /credential/schemas、GET /model/），它们无鉴权头。
• 全局错误响应：所有端点都可能返回：
  • 404 Not found——资源不存在或不属于当前用户。
  • 422 Validation Error——请求校验失败，响应体为 HTTPValidationError（{ detail: ValidationError[] }，其中 ValidationError = { loc, msg, type, input?, ctx? }）。
  • 下文各端点不再重复列出 404/422 与 ValidationError schema。
• 成功状态码约定：创建类返回 201，删除类返回 204（无响应体），其余 GET/PATCH/POST 返回 200。
• 资源域（章节）：Agent / Chat / Credential / Model / Schedule / Sessions / Workspace。
• 所有权与多用户隔离：列表类端点只返回当前 x-user-id 名下记录；按 id 操作的端点对非本人资源返回 404。
• ORM 记录通用字段：*Record（AgentRecord/CredentialRecord/ScheduleRecord/SessionRecord/TeamRecord）都含 id created_at updated_at user_id，详见末尾「关键数据模型」。

---

Agent

管理 Agent 配置（身份 + 上下文管理 + ReAct 循环）。

POST /agent/ — 创建 Agent

创建并持久化一个新的 Agent 配置。

• 请求体 CreateAgentRequest：
  • name string 必填 —— 显示名。
  • system_prompt string 默认 "You're a helpful assistant." —— 基础系统提示。
  • context_config ContextConfig —— 上下文窗口管理配置。
  • react_config ReActConfig —— ReAct 循环配置。
• 返回 201 → CreateAgentResponse：agent_id string —— 服务端分配的 Agent ID。

GET /agent/ — 列出全部 Agent

返回当前用户名下所有 Agent 记录。

• 参数：无（仅 x-user-id）。
• 返回 200 → ListAgentsResponse：agents AgentRecord[]、total int。

GET /agent/schema — 获取 Agent 表单的 JSON Schema 片段

返回前端渲染「创建/编辑 Agent 表单」用的三段自包含 JSON Schema（身份 / 上下文配置 / ReAct 配置），刻意拆成三段而非单个带 $ref 的 AgentData，便于前端按路径派生 i18n key。

• 参数：无（无 x-user-id）。
• 返回 200 → AgentSchemaResponse：identity object（name/system_prompt 的 schema）、context_config object、react_config object（均必填）。

PATCH /agent/{agent_id} — 局部更新 Agent

仅更新请求体中出现的字段，其余保持原值。

• 路径：agent_id string 必填。
• 请求体 UpdateAgentRequest（全部可空、可省略）：name string?、system_prompt string?、context_config ContextConfig?、react_config ReActConfig?。
• 返回 200 → AgentRecord（更新后的完整记录）。

DELETE /agent/{agent_id} — 删除 Agent

永久删除 Agent 配置。

• 路径：agent_id string 必填。
• 返回 204（无响应体）。

---

Chat

POST /chat/ — 触发一次聊天运行（fire-and-forget）

为指定 session 触发一次聊天运行。运行作为后台任务执行；运行期间产生的事件发布到消息总线，并下发给任何活跃的 GET /sessions/{session_id}/stream SSE 订阅者——调用方不会从本端点响应体收到事件。

• 接受的 input 取值：
  • Msg / Msg[] —— 新的用户消息。
  • UserConfirmResultEvent / ExternalExecutionResultEvent —— 恢复一个被暂停的工具调用（human-in-the-loop）。
  • null —— 从当前状态继续。
• 请求体 ChatRequest：
  • agent_id string 必填。
  • session_id string 必填 —— 目标 session。
  • input 必填（可为 null）—— 上述四类之一。
• 返回 200 → ChatTriggerResponse：status string（默认 "started"，触发成功时恒为 "started"）、session_id string 必填（回显）。

---

Credential

存储模型供应商凭据（如 API key）。凭据 data 为自由 object（按凭据类型 schema 校验）。

POST /credential/ — 创建凭据

• 请求体 CreateCredentialRequest：data object 必填 —— 凭据载荷（如 API keys）。
• 返回 201 → CreateCredentialResponse：credential_id string。

GET /credential/ — 列出全部凭据

返回当前用户名下所有凭据记录。

• 参数：无。
• 返回 200 → ListCredentialsResponse：credentials CredentialRecord[]、total int。

GET /credential/schemas — 列出所有凭据类型的 JSON Schema

返回所有已注册凭据类型的 JSON Schema，供前端动态渲染凭据创建表单。

• 参数：无（无 x-user-id）。
• 返回 200 → ListCredentialSchemasResponse：schemas object[]（每个类型一个 JSON Schema）。

PATCH /credential/{credential_id} — 更新凭据

替换已有凭据的整个载荷。

• 路径：credential_id string 必填。
• 请求体 UpdateCredentialRequest：data object 必填 —— 新载荷。
• 返回 200 → CredentialRecord。

DELETE /credential/{credential_id} — 删除凭据

• 路径：credential_id string 必填。
• 返回 204。

---

Model

GET /model/ — 列出某凭据类型下的全部候选模型

返回指定供应商（凭据类型）下的所有候选模型。

• 查询参数：provider string 必填 —— 供应商 / 凭据类型名。
• 无 x-user-id。
• 返回 200 → ListModelsResponse：models ModelCard[]、total int。

---

Schedule

定时调度（cron + APScheduler）：到点自动为指定 Agent 创建 session 并触发运行。

POST /schedule/ — 创建调度

创建调度并注册到调度器。指定的 Agent 不存在时返回 404。

• 请求体 CreateScheduleRequest：
  • name string 必填 —— 显示名。
  • description string 默认 ""。
  • cron_expression string 必填 —— 标准 5 段 cron，如 '0 9 * * 1-5'。
  • timezone string 默认 "UTC" —— IANA 时区名（如 Asia/Shanghai）。
  • agent_id string 必填 —— 触发时运行的 Agent。
  • chat_model_config ChatModelConfig 必填 —— 自动创建 session 用的模型配置。
  • enabled bool 默认 true —— 创建后是否立即生效。
  • stateful bool 默认 false —— 为 true 时连续执行共享同一 session 上下文。
  • permission_mode PermissionMode 默认 dont_ask —— 计划执行期间的权限级别。
• 返回 201 → CreateScheduleResponse：schedule_id string。

GET /schedule/ — 列出全部调度

列出当前用户的所有调度（分页列表）。

• 参数：无。
• 返回 200 → ListSchedulesResponse：schedules ScheduleRecord[]、total int。

GET /schedule/{schedule_id}/sessions — 列出某调度的执行 session

返回某调度触发过的所有 session，按创建时间倒序（最新在前）。调度不存在返回 404。

• 路径：schedule_id string 必填。
• 返回 200 → ScheduleSessionsResponse：sessions SessionRecord[]、total int。

PATCH /schedule/{schedule_id} — 局部更新调度

省略的字段保持原值。改 cron_expression 或 timezone 会立即重排 APScheduler job；enabled=false 会从调度器移除 job 但保留记录，置回 true 重新注册。

• 路径：schedule_id string 必填。
• 请求体 UpdateScheduleRequest（全部可空可省略）：name?、description?、cron_expression?、timezone?、enabled bool?、stateful bool?、permission_mode PermissionMode?。
• 返回 200 → ScheduleRecord。

DELETE /schedule/{schedule_id} — 删除调度

永久删除记录并注销 APScheduler job。调度不存在返回 404。

• 路径：schedule_id string 必填。
• 返回 204。

---

Sessions

会话：每个 (user_id, agent_id, workspace_id) 三元组至多一个 session。

POST /sessions/ — 创建（或恢复）session

为指定 Agent + workspace 创建 session；相同三元组的二次调用会更新已有 session 而非新建。Agent 或凭据不存在返回 404。

• 请求体 CreateSessionRequest：
  • agent_id string 必填。
  • workspace_id string? —— session 所属 workspace。
  • name string? —— 显示名，省略时默认当前时间。
  • chat_model_config ChatModelConfig? —— 模型供应商与参数，可后续 PATCH 设置。
  • fallback_chat_model_config ChatModelConfig? —— 主模型失败时的兜底模型，可后续 PATCH。
• 返回 201 → CreateSessionResponse：session_id string。

GET /sessions/ — 列出某 Agent 的全部 session（含富信息 SessionView）

返回该 Agent 的所有 session，每条为富化的 SessionView，一次性带齐聊天 UI 渲染所需的三块：session 记录（含 state）、当前是否有活跃运行、以及（参与 team 时）解析后的 team 详情（leader + members 及其 session id）。消息不含在内，由 /sessions/{id}/messages 分页拉取。Agent 不存在返回 404。

• 查询参数：agent_id string 必填。
• 返回 200 → ListSessionsResponse：sessions SessionView[]、total int。

GET /sessions/{session_id}/messages — 列出某 session 的消息

返回 session 已持久化的消息（按时间顺序）。

• 路径：session_id string 必填。
• 查询参数：agent_id string 必填；offset int ≥0 默认 0；limit int 1–200 默认 50。
• 返回 200 → ListMessagesResponse：messages array（消息，时间顺序；item 无 schema 约束）、is_running bool（session 当前是否在运行）。

GET /sessions/{session_id}/stream — 订阅 session 事件流（SSE）

订阅 session 的实时事件流，返回 text/event-stream：先回放当前运行 replay log 中的缓冲事件（若有运行进行中或刚结束），再实时推送 ChatService.run 产生的事件。连接保持打开直到客户端断开——同一 session 的后续运行经同一连接下发。每 30 秒发送一帧心跳注释（:\n\n）以穿透反向代理保活。

• 路径：session_id string 必填。
• 查询参数：agent_id string 必填（用于归属校验）。
• 返回 200：AgentEvent 帧 + 周期心跳组成的 SSE 流（StreamingResponse；响应 schema 为空）。

PATCH /sessions/{session_id} — 更新 session

更新已有 session 的模型配置（及名称、权限模式）。session/agent/凭据不存在返回 404。

• 路径：session_id string 必填。
• 查询参数：agent_id string 必填。
• 请求体 UpdateSessionRequest（省略保持原值）：
  • name string?。
  • chat_model_config ChatModelConfig? —— 整体替换；传 null 清空，省略不变。
  • fallback_chat_model_config ChatModelConfig? —— 同上。
  • permission_mode PermissionMode?。
• 返回 200 → SessionRecord（更新后完整记录）。

DELETE /sessions/{session_id} — 删除 session

永久删除 session 及其全部关联状态。

• 路径：session_id string 必填。
• 查询参数：agent_id string 必填 —— session 所属 Agent。
• 返回 204。

---

Workspace

会话级 workspace 的能力装配：MCP 客户端 与 Skill。所有 workspace 端点都需查询参数 agent_id + session_id（均 string 必填）。

POST /workspace/mcp — 添加 MCP

向 session 的 workspace 添加一个 MCP 客户端。

• 查询参数：agent_id、session_id（必填）。
• 请求体 MCPClient（见末尾模型）。
• 返回 201（响应体无 schema）。

GET /workspace/mcp — 列出 MCP

返回所有 MCP 客户端，附带实时工具列表与健康状态。

• 查询参数：agent_id、session_id（必填）。
• 返回 200 → MCPClientStatus[]（= MCPClient + is_healthy bool + tools ToolInfo[]）。

DELETE /workspace/mcp/{mcp_name} — 移除 MCP

按名称从 session 的 workspace 移除一个 MCP 客户端。

• 路径：mcp_name string 必填。
• 查询参数：agent_id、session_id（必填）。
• 返回 204。

POST /workspace/skill — 添加 Skill

从给定路径向 session 的 workspace 添加一个 skill。

• 查询参数：agent_id、session_id（必填）。
• 请求体 AddSkillRequest：skill_path string 必填。
• 返回 201（响应体无 schema）。

GET /workspace/skill — 列出 Skill

返回 session 的 workspace 中所有可用 skill。

• 查询参数：agent_id、session_id（必填）。
• 返回 200 → Skill[]。

DELETE /workspace/skill/{skill_name} — 移除 Skill

按名称从 session 的 workspace 移除一个 skill。

• 路径：skill_name string 必填。
• 查询参数：agent_id、session_id（必填）。
• 返回 204。

---

关键数据模型

反复被引用的核心 schema，各捕获一次。? 表示可空 / 可省略。

Agent 相关

AgentData（Agent 数据模型）

• id string —— 唯一 Agent id。
• name string 必填。
• system_prompt string（textarea）默认 "You're a helpful assistant."。
• context_config ContextConfig 必填。
• react_config ReActConfig 必填。

AgentRecord（ORM 记录）：id、created_at、updated_at、user_id（必填）、source enum user|team（默认 user）、data AgentData（必填）。

ContextConfig（上下文窗口管理）

• trigger_ratio number 默认 0.8（0 < x < 0.9）—— 触发压缩的占用比。
• reserve_ratio number 默认 0.1（0 < x < 0.9）—— 预留比。
• compression_prompt string（textarea）—— 压缩/续写摘要提示（含默认 <system-hint>… 模板）。
• summary_template string（textarea）—— 摘要回填模板（默认含 {task_overview} {current_state} {important_discoveries} {next_steps} {context_to_preserve} 占位）。
• summary_schema object —— 摘要结构 schema。
• tool_result_limit int 默认 3000 —— 工具结果最大 token 数，超出截断。

ReActConfig（推理配置）

• max_iters int 默认 20 —— 单次回复内最大推理-行动迭代数。
• stop_on_reject bool 默认 false —— 工具被拒绝执行时是否停止回复。

AgentSchemaResponse（前端表单 schema）：identity / context_config / react_config 三个自包含 object（均必填）。

Credential / Model 相关

CredentialRecord：id、created_at、updated_at、user_id、data object（必填，自由载荷，如 API keys）。

凭据类型由 GET /credential/schemas 返回的注册类型 schema 定义；data 字段对应这些 schema（如各供应商 API key 字段）。

ChatModelConfig（模型配置，被 session/schedule 复用）

• type string 必填 —— 模型/供应商类型。
• credential_id string 必填 —— 引用的凭据。
• model string 必填 —— 模型名。
• parameters object 必填 —— 模型调用参数。

ModelCard（候选模型）

• type const chat_model。
• name string 必填、label string 必填。
• status enum active|deprecated|sunset 必填。
• deprecated_at datetime? —— 弃用时间。
• input_types string[] 默认 ["text/plain"]、output_types string[] 默认 ["text/plain"]。
• context_size int >0 必填 —— 上下文大小。
• output_size int >0 必填 —— 最大输出 token 数。
• parameter_schema object 必填 —— 参数 schema。
• parameters_overrides object