zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(skills): 同步 agentscope-skill 完整版到 dev/2.0.0 主线

Browse Source 
用 feat 完整版替换 dev 旧版:references 补 studio-rest-api + v2-overview/v2-building-blocks/v2-deploy(docs.agentscope.io 2026-06-22 快照),SKILL.md 补索引。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
zizi 2026-06-22 19:24:18 +00:00
parent 14c3ce4896
commit bacb2daaa6
5 changed files with 4935 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
.claude/skills/agentscope-skill/SKILL.md
View File

@ -255,6 +255,7 @@ When writing code:
This section lists all available resources for working with AgentScope.
### Official Documentation
- **[Tutorial](https://agentscope.ai/docs/)**: Comprehensive step-by-step guide covering most functionalities in detail. This is the primary resource for learning AgentScope.
- **AgentScope 2.0 docs (mirrored offline)**: The full v2 documentation site (<https://docs.agentscope.io>) has been captured verbatim and consolidated into this skill's `references/v2-*.md` and `references/studio-rest-api.md` (snapshot 2026-06-22). Prefer these for offline, no-hallucination lookup of v2 building blocks, deployment, and the hosted Agent Service REST API; fall back to the live site for newer content.
### GitHub Resources
- **[Main Repository](https://github.com/agentscope-ai/agentscope)**: Source code, examples, and documentation
@ -301,5 +302,14 @@ python view_module_signature.py --module agentscope.agent.ReActAgent
## Reference
Located in `references/` directory of this skill.
**Hand-curated playbooks:**
- **`multi_agent_orchestration.md`**: Multi-agent orchestration concepts and implementation
- **`deployment_guide.md`**: Deployment patterns and best practices
- **`deployment_guide.md`**: Deployment patterns and best practices (agentscope-runtime: `AgentApp`, tool sandbox)
**AgentScope 2.0 official docs (mirrored & consolidated, snapshot 2026-06-22):** verbatim capture of <https://docs.agentscope.io>, boilerplate stripped, grouped by topic. Read these to look up exact v2 APIs/behavior instead of guessing.
- **`v2-overview.md`**: What's new in 2.0 / quickstart / change-log / FAQ. Start here for the 2.0 mental model and migration deltas from 1.0.
- **`v2-building-blocks.md`**: The 8 core building blocks — `agent`, `model`, `message-and-event`, `tool`, `context`, `middleware`, `permission-system`, `workspace`. The main "how to use the v2 library" reference.
- **`v2-deploy.md`**: Deploying agents as a service — `agent-service` (multi-tenant, multi-session HTTP service) and `agent-team` (leader/worker team tools).
- **`studio-rest-api.md`**: Condensed REST API reference for the hosted Studio / Agent Service (29 endpoints across agent/chat/credential/model/schedule/sessions/workspace) plus the key data models. Use when integrating with the hosted service over HTTP.
> Note (project context): in this repo AgentScope is a **long-term exploratory track**, not the MVP mainline (the agentic mainline is SAA / Spring AI Alibaba in Java). For implementation details beyond these docs, the full source clones under `/root/oss/agentscope*` are the highest authority.

397
.claude/skills/agentscope-skill/references/studio-rest-api.md Normal file
View File

@ -0,0 +1,397 @@
<!-- AgentScope 2.0 Studio/Agent Service REST API 收敛精炼 · 抓取2026-06-22 · 29端点压实自官方 api-reference -->
# 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<object> 必填 —— 参数覆盖。
### Schedule 相关
**ScheduleData**（调度配置）
- `name` string 必填、`description` string 默认 `""`。
- `enabled` bool 默认 true —— 禁用则保留记录但不触发。
- `timezone` string 默认 `"Asia/Shanghai"`（IANA 时区）。
- `cron_expression` string 必填 —— 标准 5 段 cron。
- `started_at` datetime、`ended_at` datetime?。
- `chat_model_config` `ChatModelConfig` 必填。
- `stateful` bool 默认 false —— 连续执行是否共享 session 上下文。
- `permission_mode` `PermissionMode` 默认 `dont_ask`。
- `source` `ScheduleSource` 默认 `USER`、`source_session_id` string 默认 `""`。
**ScheduleRecord**：`id`、`created_at`、`updated_at`、`user_id`（owner）、`agent_id`、`data` `ScheduleData`（均必填，除 id/时间戳外）。
**ScheduleSource** enum：`USER`（用户经 UI 手建）、`AGENT`（Agent 经工具调用自动创建）。
### Session / Team / State 相关
**SessionConfig**：`workspace_id` string 必填、`name` string、`chat_model_config` `ChatModelConfig`?、`fallback_chat_model_config` `ChatModelConfig`?。
**SessionRecord**：`id`、`created_at`、`updated_at`、`user_id`、`agent_id`、`source` `SessionSource`（默认 `user`）、`source_schedule_id` string?、`team_id` string?、`config` `SessionConfig`（必填）、`state` `AgentState`。
**SessionSource** enum：`user`、`schedule`。
**SessionView**（`GET /sessions/` 富化条目）：`session` `SessionRecord`（必填，内联 state）、`is_running` bool（必填）、`team` `TeamDetailResponse`?（`team_id` 存在时解析的 team 详情，否则 null）。
**AgentState**（持久化的 Agent 状态）：`session_id`、`summary`（string 或 TextBlock/DataBlock 数组，默认 `""`）、`context` `Msg[]`、`reply_id`、`cur_iter` int 默认 0、`permission_context` `PermissionContext`、`tool_context` `ToolContext`、`tasks_context` `TaskContext`。
**TeamData**：`name` string 必填、`description` string 默认 `""`（注入每个成员 system prompt 的团队目标/共享上下文）、`member_ids` string[]（worker agent id，每个 worker `source='team'` 且唯一一个 session）。
**TeamRecord**：`id`、`created_at`、`updated_at`、`user_id`、`session_id`（leader 的 session）、`data` `TeamData`（必填）。team 成员是 session 级：leader 由 `session_id` 标识，worker 由 agent id 标识。
**TeamDetailResponse**：`team` `TeamRecord`（必填）、`leader_agent` `AgentRecord`?（由 team `session_id` → session.agent_id 解析）、`members` `TeamMemberView[]`。
**TeamMemberView**：`agent` `AgentRecord`（必填，worker）、`session_id` string?（worker 的 session id；worker 无 session 时为 null）。
### 消息与内容块（Chat / AgentState 复用）
**Msg**（消息类）：`name` string 必填、`content` array 必填（由下列 block 组成）、`role` enum `user`|`assistant`|`system` 必填、`id`、`metadata` object、`created_at`、`finished_at` string?、`usage` `Usage`?。
`content` 可含的 block（均有 `type` 判别字段 + `id`）：
- **TextBlock** `type=text`：`text` string 必填。
- **ThinkingBlock** `type=thinking`：`thinking` string 必填；允许额外 provider 字段（如 Anthropic `signature`）。
- **HintBlock** `type=hint`：`hint`（string 或 TextBlock/DataBlock 数组）必填、`source` string? —— 推理-行动循环中给 LLM 的提示，转为 user 消息下发。
- **ToolCallBlock** `type=tool_call`：`id`/`name`/`input`(string) 必填、`state` `ToolCallState` 默认 `pending`、`suggested_rules` `PermissionRule[]`；允许额外字段（如 OpenAI `call_id`）。
- **ToolResultBlock** `type=tool_result`：`id`/`name`/`output` 必填（output 为 string 或 TextBlock/DataBlock 数组）、`state` `ToolResultState` 默认 `running`。
- **DataBlock** `type=data`：`source`（`Base64Source` | `URLSource`）必填、`name` string? —— 二进制内容（图/音/视频等）。
**Base64Source** `type=base64`：`data` string 必填、`media_type` string 必填。
**URLSource** `type=url`：`url`（uri，必填）、`media_type` string 必填。
**Usage**：`input_tokens` int、`output_tokens` int（均必填）。
### HITL 恢复事件（Chat input）
**UserConfirmResultEvent** `type=USER_CONFIRM_RESULT`：`reply_id` string 必填、`confirm_results` `ConfirmResult[]` 必填、`id`/`created_at`。
- **ConfirmResult**：`confirmed` bool 必填、`tool_call` `ToolCallBlock` 必填、`rules` `PermissionRule[]`?。
**ExternalExecutionResultEvent** `type=EXTERNAL_EXECUTION_RESULT`：`reply_id` string 必填、`execution_results` `ToolResultBlock[]` 必填、`id`/`created_at`。
### 权限模型
**PermissionMode** enum：`default`（每次操作都需显式授权，最安全）、`accept_edits`（工作目录内自动放行读/写/文件系统命令）、`explore`（只读：放行 Read/Grep/Glob，拒绝 Write/Edit/Bash）、`bypass`（全部自动放行，无权限检查，沙箱/全信任）、`dont_ask`（把所有 ASK 决策转为 DENY，用于无人值守的计划任务）。
**PermissionBehavior** enum：`allow`、`deny`、`ask`、`passthrough`（交回权限引擎继续规则匹配）。
**PermissionRule**：`tool_name` string 必填、`rule_content` string?（必填字段但可为 null）、`behavior` `PermissionBehavior` 必填、`source` string 必填。`rule_content` 语义随工具不同：Bash=命令子串匹配；Write/Read=文件 glob；其他工具=工具自定义过滤模式。
**PermissionContext**：`mode` `PermissionMode`（默认 `default`）、`working_directories` map<string,`AdditionalWorkingDirectory`>、`allow_rules`/`deny_rules`/`ask_rules` 均为 map<string,`PermissionRule[]`>。
**AdditionalWorkingDirectory**：`path` string 必填、`source` string 必填——纳入权限范围的额外目录（ACCEPT_EDITS 下判定可自动放行的路径）。
### 工具与任务上下文
**ToolContext**：`max_cache_files` int 默认 100（>1）、`max_cache_bytes` number 默认 25000（>10000）、`read_file_cache` `ReadCacheEntry[]`、`activated_groups` string[]。
**ReadCacheEntry**：`lines` string[]、`updated_at` number、`bytes` number、`file_path` string（均必填）。
**TaskContext**：`tasks` `Task[]`。
**Task**：`subject`/`description`/`metadata` 必填、`created_at`、`state` enum `pending`|`in_progress`|`completed`（默认 `pending`）、`id`、`owner` string?、`blocks` string[]、`blocked_by` string[]。
**ToolCallState** enum：`pending`|`asking`|`allowed`|`submitted`|`finished`。
**ToolResultState** enum：`success`|`error`|`interrupted`|`denied`|`running`。
### Workspace：MCP 与 Skill
**MCPClient**（统一 MCP 客户端）
- `name` string 必填 —— MCP 名。
- `is_stateful` bool 必填 —— 是否有状态连接（需显式 connect/close）。STDIO MCP 必须有状态；HTTP MCP 可有/无状态。
- `mcp_config`（必填，`type` 判别）：`StdioMCPConfig`（`type=stdio_mcp`）或 `HttpMCPConfig`（`type=http_mcp`）。
- `enable_tools` string[]?、`disable_tools` string[]?、`execution_timeout` number?。
**MCPClientStatus** = `MCPClient` + `is_healthy` bool（默认 false）+ `tools` `ToolInfo[]`（实时工具列表）。
**StdioMCPConfig** `type=stdio_mcp`：`command` string 必填、`args` string[]?、`env` map<string,string>?、`cwd` string/path?、`encoding_error_handler` enum `strict`|`ignore`|`replace`（默认 `strict`）。
**HttpMCPConfig** `type=http_mcp`：`url` string 必填、`headers` map<string,string>?、`timeout` number? 默认 30（秒）。
**ToolInfo**：`name` string 必填、`description` string?。
**Skill**（Agent skill）：`name`/`description`/`dir`/`markdown`/`updated_at`(number) 均必填。
**AddSkillRequest**：`skill_path` string 必填。

3311
.claude/skills/agentscope-skill/references/v2-building-blocks.md Normal file
View File

File diff suppressed because it is too large Load Diff

893
.claude/skills/agentscope-skill/references/v2-deploy.md Normal file
View File

@ -0,0 +1,893 @@
<!-- AgentScope 2.0 官方文档收敛 · 部署篇 · 抓取2026-06-22 · 含: agent-service(托管HTTP服务)/agent-team(Leader-worker团队) -->
<!-- ===== source: v2/deploy/agent-service.md ===== -->
# Agent Service
> Host your agent as a multi-tenant, multi-session HTTP service
Agent Service is the FastAPI-based hosting layer that turns AgentScope agents into a **multi-tenant, multi-session HTTP service**. It owns everything *around* the agent — request routing, per-user resource lifecycle, session state, persistence, scheduling, and tool offloading — so that the agent code you wrote against [`Agent`](/v2/building-blocks/agent) can serve production traffic without being rewritten.
What sets it apart:
* **Production backbone for live agents** — agent runs, background tasks, schedules, and the tool/MCP/skill/workspace lifecycle are managed end-to-end, with session streams that fan out to multiple subscribers and replay buffered history on reconnect.
* **Schema-driven frontend** — credentials publish JSON schemas and models expose declarative cards (input/output types, context size, parameter schemas), so the UI can render forms and capability badges without coupling to provider-specific code.
* **Multi-tenant by construction** — credentials, agents, sessions, schedules, and messages are all owned by the request's `user_id`, and ownership is enforced at the routing layer — one deployment serves many users with no per-tenant code paths.
* **Modular and extensible** — authentication, chat protocols, workspace isolation strategy, storage backend, and the set of model providers and credential types are all open at the boundary, swappable without touching framework code.
### Capabilities
| Capability | Description |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent teams | A leader agent spawns worker agents and coordinates them through built-in team tools; see the [Agent Team](/v2/deploy/agent-team) chapter. |
| Workspace management | Pluggable workspace isolation (built-in: per-agent; extensible to per-session or per-user) for the agent's filesystem, MCP clients, and skills. |
| Background task offloading | Long-running tool calls move to background; their results are delivered back through the session's event stream when they finish. |
| Cron scheduling | Time-based agent execution with stateful or stateless sessions; schedules persist across restarts. |
| Session replay | Late-joining clients to the per-session SSE stream receive buffered history before live events, so multiple tabs or a reconnecting frontend stay in sync. |
| Protocol adaptation | Middleware-based conversion to external protocols (AG-UI, A2A, etc.) on top of AgentScope's native event stream. |
| Distributed deployment <Badge color="yellow" size="sm">WIP</Badge> | All shared state lives in Redis (storage + message bus), so multiple worker processes — or multiple nodes — can serve one logical service. |
<Note>
The service does **not** include a built-in user authentication system. It provides a placeholder `X-User-ID` header dependency that you replace with your own auth middleware (JWT, OAuth, session tokens, etc.).
</Note>
## Quickstart
The fastest way to see Agent Service in action is to run the bundled example backend together with the example frontend — both ship inside the AgentScope repo.
### Try the bundled example
The [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) directory boots a ready-to-use service, and [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) is a matching React frontend that talks to it. Together they give you a working playground for every capability above in a few minutes.
<Frame caption="Background task offloading — a long-running tool moves to a background watcher; the result later wakes the agent up and the conversation resumes.">
<img src="https://mintcdn.com/agentscope-ai-786677c7/c8Op3M8_8-WXpeVH/images/bg_tool.gif?s=ecba271192d28e8d36ef6ba02ef5cc7f" alt="Background tool offloading and wakeup demo" width="1920" height="1080" data-path="images/bg_tool.gif" />
</Frame>
<Frame caption="Permission control in bypass mode — the agent runs end-to-end without pausing for tool-call confirmations.">
<img src="https://mintcdn.com/agentscope-ai-786677c7/c8Op3M8_8-WXpeVH/images/permission_bypass.gif?s=45da293c3c8b1b819f2e87924652d563" alt="Permission system in bypass mode" width="1920" height="1080" data-path="images/permission_bypass.gif" />
</Frame>
<Frame caption="Task planning — the agent breaks complex work into a tracked plan and updates it as it goes.">
<img src="https://mintcdn.com/agentscope-ai-786677c7/c8Op3M8_8-WXpeVH/images/task.gif?s=d9bf05e01cde9c044cfe558a4de67d2f" alt="Task planning demo" width="1920" height="1080" data-path="images/task.gif" />
</Frame>
<Frame caption="Agent team — a leader agent spawns workers and coordinates them through the built-in team tools.">
<img src="https://mintcdn.com/agentscope-ai-786677c7/c8Op3M8_8-WXpeVH/images/team.gif?s=604f394f94cca0dbca8fdeee75a0f7ff" alt="Agent team coordination demo" width="1920" height="1080" data-path="images/team.gif" />
</Frame>
<Steps>
<Step title="Clone the repository">
```bash
git clone https://github.com/agentscope-ai/agentscope.git
cd agentscope
```
</Step>
<Step title="Start the example backend">
Make sure a local Redis is reachable (the example expects `localhost:6379`), then launch the service:
```bash
cd examples/agent_service
python main.py
```
The service comes up on `http://localhost:8000`.
</Step>
<Step title="Start the example frontend">
In another terminal, install and run the web UI:
```bash
cd examples/web_ui
pnpm install
pnpm dev
```
Open the URL the dev server prints (typically `http://localhost:5173`) and the frontend will connect to the backend you started in step 2.
</Step>
</Steps>
Once both are running, the same UI lets you exercise every capability the service ships with:
* **Permission control** — tools that touch the system pause for confirmation; explore-mode locks the agent to read-only operations.
* **Background task offloading** — long-running tool calls move to the background and their results stream in when they finish, without blocking the conversation.
* **Task planning** — the agent breaks complex work into a tracked plan and updates it as it goes.
* **Agent teams** — a leader agent spawns workers and coordinates them through the team tools.
* **Scheduled runs** — cron-driven agents that fire on their own and report back to the same session stream.
### From your own code
When you want to embed the service in your own deployment instead of running the example, build the FastAPI app yourself with `create_app`. The minimum to get a service running is a storage backend, a message bus, and a workspace manager. The examples below boot a service on port 8000 backed by Redis — pick the workspace backend that matches where you want the agent's tools to execute.
<CodeGroup>
```python Local filesystem
import uvicorn
from agentscope.app import create_app
from agentscope.app.storage import RedisStorage
from agentscope.app.message_bus import RedisMessageBus
from agentscope.app.workspace_manager import LocalWorkspaceManager
# Persistence layer for agents, sessions, credentials, messages, and schedules.
# Its connection pool is opened on app startup and closed on shutdown.
storage = RedisStorage(host="localhost", port=6379)
# Redis-backed message bus: session locks, replay logs, inbox queues, and
# wakeup signals that decouple chat triggering from event delivery and
# let multiple worker processes share one logical service.
message_bus = RedisMessageBus(host="localhost", port=6379)
# Workspace lifecycle — working directory, MCP clients, skills.
# The built-in manager isolates per agent: sessions of the same agent
# share one workspace. Idle workspaces are evicted after `ttl` seconds.
workspace_manager = LocalWorkspaceManager(
basedir="/data/workspaces",
ttl=3600.0,
)
app = create_app(
storage=storage,
message_bus=message_bus,
workspace_manager=workspace_manager,
)
uvicorn.run(app, host="0.0.0.0", port=8000)
```
```python Docker sandbox
import uvicorn
from agentscope.app import create_app
from agentscope.app.storage import RedisStorage
from agentscope.app.message_bus import RedisMessageBus
from agentscope.app.workspace_manager import DockerWorkspaceManager
storage = RedisStorage(host="localhost", port=6379)
message_bus = RedisMessageBus(host="localhost", port=6379)
# Each workspace runs inside its own local Docker container for isolation.
# Per-user/per-agent host workdirs live under `basedir` and are bind-mounted
# into each container.
workspace_manager = DockerWorkspaceManager(basedir="/data/docker-workspaces")
app = create_app(
storage=storage,
message_bus=message_bus,
workspace_manager=workspace_manager,
)
uvicorn.run(app, host="0.0.0.0", port=8000)
```
```python E2B
import uvicorn
from agentscope.app import create_app
from agentscope.app.storage import RedisStorage
from agentscope.app.message_bus import RedisMessageBus
from agentscope.app.workspace_manager import E2BWorkspaceManager
storage = RedisStorage(host="localhost", port=6379)
message_bus = RedisMessageBus(host="localhost", port=6379)
# Each workspace runs inside a remote E2B cloud sandbox.
# Provide `api_key` here or set the `E2B_API_KEY` environment variable.
workspace_manager = E2BWorkspaceManager()
app = create_app(
storage=storage,
message_bus=message_bus,
workspace_manager=workspace_manager,
)
uvicorn.run(app, host="0.0.0.0", port=8000)
```
</CodeGroup>
### create\_app parameters
<ParamField path="storage" type="StorageBase" required>
The storage backend for persisting agents, sessions, credentials, messages, and schedules. Its lifecycle (`__aenter__` / `__aexit__`) is managed by the app lifespan.
</ParamField>
<ParamField path="message_bus" type="MessageBus" required>
Redis-backed primitives — session locks, replay logs, inbox queues, and wakeup signals — that decouple chat triggering from event delivery. Required because every code path that delivers events to the frontend (`POST /chat`, scheduled fires, team messages, background-tool completions) goes through it, and because it is what makes multi-process deployments possible.
</ParamField>
<ParamField path="workspace_manager" type="WorkspaceManagerBase" required>
Manages workspaces (file storage, MCP servers, skills) with TTL-based caching. The built-in `LocalWorkspaceManager` isolates per agent; see [Workspace implementation and isolation](#workspace-implementation-and-isolation) for other strategies.
</ParamField>
<ParamField path="extra_credentials" type="list[Type[CredentialBase]] | None" default="None">
Additional credential types to register. Each class is registered with `CredentialFactory` before the app starts.
</ParamField>
<ParamField path="extra_middlewares" type="list[Middleware] | None" default="None">
Additional ASGI middlewares (e.g., protocol adapters, CORS, auth).
</ParamField>
<ParamField path="extra_agent_middlewares" type="AgentMiddlewareFactory | None" default="None">
Async factory `(user_id, agent_id, session_id) -> Awaitable[list[MiddlewareBase]]` invoked once per agent assembly (per chat turn or scheduled trigger). Returned middlewares are appended to the framework-supplied ones (e.g., `ToolOffloadMiddleware`) before the agent runs, so the factory can produce per-user / per-session middlewares such as audit logging, tenant isolation, or custom auth.
</ParamField>
<ParamField path="extra_agent_tools" type="AgentToolFactory | None" default="None">
Async factory `(user_id, agent_id, session_id) -> Awaitable[list[ToolBase]]` invoked once per agent assembly. Returned tools are merged into the toolkit's `"basic"` group alongside the workspace-derived tools, so tool availability can vary per caller (per-tenant integrations, user-specific credentials).
</ParamField>
<ParamField path="sub_agent_templates" type="list[SubAgentTemplate] | None" default="None">
Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. `"researcher"`, `"coder"`) with pre-configured system prompt, permission context, and task context. When registered, the `AgentCreate` tool exposes a `subagent_type` parameter so the leader agent can route to the appropriate template. See [Custom sub-agent types](/v2/deploy/agent-team#custom-sub-agent-types) for details.
</ParamField>
<ParamField path="title" type="str" default="AgentScope">
OpenAPI title shown in the docs UI.
</ParamField>
<ParamField path="version" type="str" default="2.0.0">
API version shown in the docs UI.
</ParamField>
<Warning>
The default `X-User-ID` header provides no authentication. Replace it with a real auth integration before deploying — see [User authentication](#user-authentication).
</Warning>
### Typical operation flow
Once the server is running, drive it through the resources defined in the resource model. The flow below is the path a chat session usually takes — each step is one or two REST calls.
<Steps>
<Step title="Create an agent">
Register the agent's identity — display name, system prompt, and runtime configuration. The same agent can drive many sessions under different models.
```http
POST /agent
```
</Step>
<Step title="Create and configure a credential">
Discover each provider's form fields with `GET /credential/schemas`, then save the API key. One credential can be reused across many sessions and agents.
```http
GET /credential/schemas
POST /credential
```
</Step>
<Step title="Create a session and select a model">
Create a session bound to the agent and attach a model configuration — provider, model name, parameters, and the credential to call it with. The session owns the runtime state from here on.
```http
POST /sessions
```
</Step>
<Step title="Configure MCPs and skills (optional)">
Attach MCP clients and skills to the session's workspace if the agent needs tools beyond its built-ins. Out of the box, every agent already has access to the workspace's built-in tools (filesystem, shell, search, …), task-planning tools, schedule and background-task controls, and — when the session is a team leader or member — the team coordination tools described in [Agent Team](/v2/deploy/agent-team). Anything you pass via `extra_agent_tools` in `create_app` is merged in alongside.
```http
POST /workspace/mcp
POST /workspace/skill
```
</Step>
<Step title="Start chatting">
Fire a chat run by posting a user `Msg` to `/chat`. The endpoint returns immediately with `{"status": "started", "session_id": "..."}` — events are delivered out-of-band on the per-session SSE stream `GET /sessions/{id}/stream`, which any number of clients can subscribe to and which replays buffered history to late joiners before serving live events.
```http
POST /chat
GET /sessions/{session_id}/stream
```
</Step>
</Steps>
Trigger a run:
```bash
curl -X POST http://localhost:8000/chat \
-H "X-User-ID: alice" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent-xxx",
"session_id": "session-xxx",
"input": {
"name": "alice",
"role": "user",
"content": [{"type": "text", "text": "Hello"}]
}
}'
```
Subscribe to the session's event stream in parallel (or before triggering — the stream stays open across runs and broadcasts everything the session produces, including scheduled fires and background-tool completions):
```bash
curl -N -H "X-User-ID: alice" \
"http://localhost:8000/sessions/session-xxx/stream?agent_id=agent-xxx"
```
For a **scheduled run**, complete steps 1 and 2, then create a schedule that targets the agent — the scheduler creates the session (stateful or stateless) and triggers the run on the cron expression you provide. No `/chat` call is needed; the agent runs autonomously when the cron fires.
```http
POST /schedule
```
## Resource Model
Every operation in Agent Service is scoped to a `user_id` resolved from the request. Below that boundary, the service manages seven resource types — six persisted (left half of the diagram) plus the message bus that ties their runtime behavior together (right half):
```mermaid
flowchart TB
User([User])
User --> Cred[Credential]
User --> Agent[Agent]
User --> Sched[Schedule]
Agent -- "1 : N" --> Session[Session]
Session -- "references" --> Cred
Session -- "bound to" --> WS[Workspace]
Session -- "owns" --> Msg[Messages]
Sched -- "targets" --> Agent
Sched -- "triggers" --> Session
Bus{{MessageBus}}
Sched -. "inbox + wakeup" .-> Bus
Bus -. "drives runs" .-> Session
Session -. "publishes events" .-> Bus
```
| Resource | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User** | Opaque tenant identifier resolved from the request. The service models no user system of its own; you plug yours in via `get_current_user_id`. |
| **Credential** | Connection configuration for a model provider — an API key plus provider-specific settings. Reusable across many agents and sessions. |
| **Agent** | Display name, system prompt, and runtime configuration (context, ReAct loop). The reusable template — identity belongs to the agent, runtime state belongs to the session. |
| **Workspace** | The agent's runtime environment — working directory, MCP clients, skills, offloaded context. How workspaces map to users / agents / sessions is decided by the workspace manager. |
| **Session** | One ongoing exchange between a user and an agent. Carries the agent state (working memory, in-flight reply, permission context), persisted message transcript, and the LLM configuration the session runs under. |
| **Schedule** | Fires an agent on a cron expression. Each fire runs inside a session — fresh per execution (stateless) or reused so context accumulates (stateful). Schedules persist across restarts. |
| **MessageBus** | Redis-backed runtime layer — session locks, replay logs, inbox queues, wakeup signals. The single delivery channel for scheduled fires, team messages, and background-tool completions to reach idle sessions; also what makes multi-process operation possible. |
<Tip>
The shape to remember: **agents are reusable templates, sessions are the unit of runtime state**, and the message bus is what brings idle sessions back to life when something external (a schedule, a teammate, a background tool) has something to say.
</Tip>
## API Overview
The service exposes the resources from the resource model as REST endpoints, plus the streaming chat endpoint. The table below groups them by category; full request and response shapes are documented in the service's OpenAPI specification.
| Category | Endpoints | Description |
| ------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Chat | `POST /chat` | Fire a chat run for a session; returns `ChatTriggerResponse` JSON. Events are delivered out-of-band on the per-session stream. |
| Session stream | `GET /sessions/{id}/stream` | Per-session SSE stream of `AgentEvent` objects, with buffered replay for late joiners and multi-subscriber fan-out. |
| Sessions | `GET/POST/PATCH/DELETE /sessions` | Create and manage chat sessions, including model binding and permission level. |
| Messages | `GET /sessions/{id}/messages` | Paginated message transcript for a session. |
| Agents | `GET/POST/PATCH/DELETE /agent` | Manage agent records — display name, system prompt, runtime config. |
| Credentials | `GET/POST/PATCH/DELETE /credential` | CRUD for per-provider API keys and connection configs. |
| Credential schemas | `GET /credential/schemas` | Discover all registered credential types and their JSON parameter schemas for form rendering. |
| Models | `GET /model?provider=<name>` | List candidate models for a provider, with their declarative `ModelCard` (capabilities and parameter schemas). |
| Schedules | `GET/POST/PATCH/DELETE /schedule`, `GET /schedule/{id}/sessions` | Manage cron-based agent execution, stateful or stateless. |
| Workspace MCPs | `GET/POST /workspace/mcp`, `DELETE /workspace/mcp/{mcp_name}` | Manage MCP clients attached to the session's workspace. |
| Workspace skills | `GET/POST /workspace/skill`, `DELETE /workspace/skill/{skill_name}` | Manage skills available in the session's workspace. |
## Customization
The service is open at every infrastructure boundary. The sections below describe what is built in and how to plug in your own.
### Agent chat protocol
The per-session stream endpoint (`GET /sessions/{id}/stream`) emits AgentScope's native [`AgentEvent`](/v2/building-blocks/message-and-event) stream over SSE. To serve the same agent under a different frontend protocol, install a protocol middleware that intercepts the SSE stream and rewrites each frame.
AgentScope ships with `AGUIProtocolMiddleware` for the [AG-UI](https://docs.ag-ui.com/) protocol. Install it via `extra_middlewares`:
```python
from fastapi.middleware import Middleware
from agentscope.app import create_app, AGUIProtocolMiddleware
app = create_app(
storage=storage,
extra_middlewares=[
Middleware(AGUIProtocolMiddleware),
],
)
```
To add a new protocol, subclass `ProtocolMiddlewareBase` and implement `_convert_to_protocol`:
```python
from agentscope.app import ProtocolMiddlewareBase
from agentscope.event import AgentEvent
class MyProtocolMiddleware(ProtocolMiddlewareBase):
def _convert_to_protocol(self, event: AgentEvent) -> dict:
# Convert AgentEvent to your protocol's frame format.
return {"type": event.type, "data": event.model_dump()}
```
The middleware automatically intercepts `StreamingResponse` objects from the session stream endpoint, deserializes each SSE frame back into an `AgentEvent`, calls `_convert_to_protocol()` to produce the target format, and re-serializes the converted frame.
### User authentication
The built-in `get_current_user_id` dependency extracts the caller identity from the `X-User-ID` request header — a placeholder, not authentication. Override it with your own dependency to integrate any identity system.
JWT bearer token:
```python
from fastapi import Header, HTTPException, status
async def get_current_user_id(
authorization: str = Header(...),
) -> str:
try:
payload = decode_jwt(authorization.removeprefix("Bearer "))
return payload["sub"]
except InvalidTokenError:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid authentication token.",
)
```
OAuth2 password flow:
```python
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
async def get_current_user_id(token: str = Depends(oauth2_scheme)) -> str:
user = await verify_oauth_token(token)
if user is None:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
return user.id
```
Wire your override by replacing the dependency on the FastAPI app:
```python
from agentscope.app.deps import get_current_user_id as default_dependency
app.dependency_overrides[default_dependency] = get_current_user_id
```
<Warning>
The default `X-User-ID` header provides no authentication. Always replace it with a secure mechanism before deploying to production.
</Warning>
### Workspace implementation and isolation
Two independent axes are configurable:
* **Workspace backend** — what runtime environment the agent runs in. Built-in implementations include `LocalWorkspace`, `DockerWorkspace`, and `E2BWorkspace`. New backends implement the workspace interface and can wrap container images, sandboxes, or remote VMs.
* **Isolation strategy** — how workspaces map to users, agents, and sessions. The built-in `LocalWorkspaceManager` keys workspaces by `agent_id`: all sessions of the same agent share one workspace. To switch to per-user or per-session isolation, subclass `WorkspaceManagerBase` and override `get_workspace` with your own keying strategy.
```python
from agentscope.app.workspace_manager import WorkspaceManagerBase
from agentscope.workspace import WorkspaceBase
class PerSessionWorkspaceManager(WorkspaceManagerBase):
async def get_workspace(
self,
user_id: str,
agent_id: str,
session_id: str,
workspace_id: str,
) -> WorkspaceBase:
# Resolve an initialized workspace; key by session_id for per-session isolation.
...
async def create_workspace(
self,
user_id: str,
agent_id: str,
session_id: str,
) -> WorkspaceBase:
# Allocate a fresh workspace and register it in the cache.
...
async def close(self, workspace_id: str) -> None:
# Close and evict a single workspace.
...
async def close_all(self) -> None:
# Close every cached workspace; called on app shutdown.
...
```
### API credentials
A new credential type is a pair of classes: a `CredentialBase` subclass that captures the connection config (and publishes its JSON schema for form rendering), and a `ChatModelBase` subclass that implements the actual streaming chat protocol against the provider's API. The credential class is the entry point — it tells the service which chat model class to instantiate.
```python
from agentscope.credential import CredentialBase
from agentscope.model import ChatModelBase
class MyProviderChatModel(ChatModelBase):
# Implement the streaming chat interface against the provider's API.
...
class MyProviderCredential(CredentialBase):
api_key: str
endpoint: str = "https://api.my-provider.com"
@classmethod
def get_chat_model_class(cls):
return MyProviderChatModel
```
Register the credential class with the app — it becomes immediately usable by clients:
```python
app = create_app(
storage=storage,
extra_credentials=[MyProviderCredential],
)
```
The service automatically exposes the credential's JSON schema under `GET /credential/schemas`, and `GET /model?provider=<name>` routes to the chat model class returned by `get_chat_model_class()`.
### Provider models
The model list returned by `GET /model?provider=<name>` is built from `ModelCard` instances — declarative metadata records that tell the frontend how to display each model and what request parameters are valid. Each chat model exposes its catalog through `list_models()`, which by default loads `ModelCard` entries from YAML files in the provider's model directory; `ModelCard.from_yaml()` parses each YAML and merges its overrides into the base parameter schema supplied by the chat model's parameters class.
A model card carries the following fields:
| Field | Description |
| ---------------------- | ----------------------------------------------------------------------------- |
| `name` | Provider-side model identifier. |
| `label` | Display name shown in the UI. |
| `status` | One of `active`, `deprecated`, `sunset`. |
| `deprecated_at` | Deprecation timestamp, if any. |
| `input_types` | MIME types the model accepts (e.g., `text/plain`, `image/png`, `video/mp4`). |
| `output_types` | MIME types the model emits (e.g., `text/plain`, `application/x-thinking`). |
| `context_size` | Maximum context window in tokens. |
| `output_size` | Maximum output tokens. |
| `parameter_schema` | JSON schema for the request parameters, auto-merged with per-model overrides. |
| `parameters_overrides` | Per-model deltas applied on top of the base parameter schema. |
Example YAML for a multimodal model that accepts text, images, and video and emits text plus thinking traces:
```yaml qwen3.6-plus.yaml
name: qwen3.6-plus
label: Qwen3.6-Plus
status: active
input_types:
- text/plain
- application/x-thinking
- image/bmp
- image/jpeg
- image/png
- image/tiff
- image/webp
- image/heic
- video/mp4
output_types:
- text/plain
- application/x-thinking
context_size: 1000000
output_size: 65536
parameter_overrides:
max_tokens: {"maximum": 65536}
```
To add a new model under an existing provider, drop a YAML file alongside the others in the provider's model directory — the loader picks it up automatically and the new entry shows up in `GET /model?provider=<name>`.
### Storage backend
The `StorageBase` abstract class defines the persistence contract for agents, sessions, credentials, messages, and schedules. AgentScope ships with `RedisStorage` as the built-in implementation:
```python
from agentscope.app.storage import RedisStorage
storage = RedisStorage(
host="localhost",
port=6379,
db=0,
password="your-password",
)
```
To use another database, implement the same interface:
```python
from agentscope.app.storage import StorageBase
class PostgresStorage(StorageBase):
async def __aenter__(self):
# Open connection pool.
...
async def __aexit__(self, exc_type, exc_val, exc_tb):
# Close connection pool.
...
# Implement CRUD methods for each record type:
# agents, sessions, credentials, messages, schedules, teams.
...
app = create_app(
storage=PostgresStorage(dsn="postgresql://..."),
message_bus=message_bus,
workspace_manager=workspace_manager,
)
```
The records the storage layer manages:
| Record | Description |
| ------------------ | -------------------------------------------------------------------------- |
| `AgentRecord` | Agent configuration (name, system prompt, context config, react config). |
| `SessionRecord` | Session state including `AgentState`, model config, and workspace binding. |
| `CredentialRecord` | Encrypted model provider API keys. |
| `ScheduleRecord` | Cron schedule definitions with execution history. |
| `TeamRecord` | Team identity, leader binding, and worker member list. |
| `Msg` | Persisted messages per session with pagination support. |
## Service Internals
For developers who need to extend or embed the actual implementation of Agent Service in AgentScope, this section describes how the FastAPI app is wired together — what runs at startup, which managers hold runtime state, where middlewares sit in the request path, and how routers get hold of those resources.
```mermaid
flowchart TB
Client([Client / Frontend])
subgraph FastAPI ["FastAPI Application"]
direction TB
subgraph ASGI ["ASGI Middlewares"]
PM[Protocol Middleware]
OT[OpenTelemetry]
end
Router[API Routers]
subgraph Lifespan ["Lifespan-bound Resources"]
Bus[MessageBus]
BTM[BackgroundTaskManager]
SCH[SchedulerManager]
WM[WorkspaceManager]
WD[WakeupDispatcher]
CS[ChatService]
end
subgraph AgentMW ["Agent-level Middlewares"]
IM[InboxMiddleware]
TOM[ToolOffloadMiddleware]
SCM[StateChangeMiddleware]
end
end
Storage[(Storage)]
Client --> ASGI --> Router
Router -- "Depends()" --> Lifespan
Router --> CS
CS --> Storage
CS --> AgentMW --> Agent([Agent Instance])
SCH -- "inbox_push + enqueue_wakeup" --> Bus
TOM -- "inbox_push + enqueue_wakeup" --> Bus
Bus --> WD
WD --> CS
```
### Lifespan
The lifespan context manager runs once per process. Built with `AsyncExitStack`, it enters resources in order — storage → message bus → workspace manager → background task manager → scheduler manager → chat service → wakeup dispatcher — and tears them down in reverse on shutdown. If any startup step raises, every previously-entered resource is still cleaned up. The scheduler restores persisted cron jobs on entry so they survive restarts.
### Managers
The following resources are bound to the FastAPI app state during the lifespan and shared across all requests:
| Resource | Responsibility |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `MessageBus` | Redis-backed primitives (session locks + replay log, inbox queues, wakeup signals). The single delivery channel for scheduled fires, team messages, and background-tool completions to reach idle sessions; also what enables multi-process operation. |
| `WakeupDispatcher` | One per process. Subscribes to the wakeup signal and, for each enqueued wakeup, drives `ChatService.run` for the target session. |
| `BackgroundTaskManager` | Pure asyncio task registry. `ToolOffloadMiddleware` spawns watcher tasks here; results are pushed back through the message bus (inbox + wakeup), not held in this manager. |
| `SchedulerManager` | APScheduler-backed cron execution. On fire, the trigger pushes a `HintBlock` to the target session's inbox and enqueues a wakeup — no direct call into `ChatService`. |
| `WorkspaceManager` | Workspace lifecycle and TTL-based caching; the isolation key (per-agent, per-user, per-session) is decided by the subclass. |
| `ChatService` | Single entry point for running a session. Loads records, assembles the toolkit, builds middlewares, takes the bus session lock, and drives the agent's reply stream. |
### Middlewares
Two distinct middleware layers operate at different scopes.
**ASGI middlewares** wrap every HTTP request. The two categories used in practice are **protocol middlewares** (e.g., `AGUIProtocolMiddleware`), which intercept SSE responses from the session stream endpoint and rewrite each frame into the target protocol, and **observability middlewares** (e.g., OpenTelemetry tracing). Both install via `extra_middlewares`.
**Agent-level middlewares** wrap each call to the agent inside `ChatService`. They are exposed under `agentscope.app.middleware` and the framework always installs three:
* `InboxMiddleware` — the sole owner of hint injection. Before each reasoning step it drains the session's inbox and yields the queued `HintBlock`s as `HintBlockEvent`s, so scheduled fires, team messages, and offloaded-tool results all flow into the agent's context through the same path.
* `ToolOffloadMiddleware` — when a tool call exceeds its timeout, the call is moved to a background watcher task and a synthetic placeholder is yielded to the agent. When the watcher finishes, the result is pushed back to the session's inbox plus a wakeup, so the next run picks it up.
* `StateChangeMiddleware` — emits `CustomEvent`s when the agent state changes (e.g., `tasks_context`, `permission_context`) so the frontend can react without reading raw state snapshots.
To add your own (audit logging, tenant isolation, custom auth, …), pass an `extra_agent_middlewares` factory to `create_app`. The factory runs once per agent assembly and its middlewares are appended to the framework-supplied ones.
### Dependencies
Routers receive application state through FastAPI's `Depends()`. The standard injectables (in `agentscope.app.deps`) are:
| Dependency | Returns |
| ----------------------------- | ---------------------------------------------------------------- |
| `get_current_user_id` | The caller's user id — overridable to integrate any auth system. |
| `get_storage` | The `StorageBase` instance bound to the app. |
| `get_message_bus` | The `MessageBus` instance bound to the app. |
| `get_workspace_manager` | The lifespan-bound `WorkspaceManager`. |
| `get_background_task_manager` | The lifespan-bound `BackgroundTaskManager`. |
| `get_scheduler_manager` | The lifespan-bound `SchedulerManager`. |
| `get_chat_service` | The lifespan-bound `ChatService`. |
## Further Reading
<CardGroup cols={2}>
<Card title="Agent" icon="robot" href="/v2/building-blocks/agent">
Core agent abstraction and the ReAct loop
</Card>
<Card title="Message & Event" icon="envelope" href="/v2/building-blocks/message-and-event">
Event streaming and message reconstruction
</Card>
<Card title="Tool" icon="wrench" href="/v2/building-blocks/tool">
Built-in and custom tools including external execution
</Card>
<Card title="Context" icon="database" href="/v2/building-blocks/context">
Context compression and workspace offloading
</Card>
</CardGroup>
<!-- ===== source: v2/deploy/agent-team.md ===== -->
# Agent Team
> Leader agents that spawn and coordinate worker agents through built-in team tools
Agent Team is the multi-agent layer built on top of [Agent Service](/v2/deploy/agent-service). A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework.
## Quickstart
The bundled [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) backend ships with the team tools enabled, and the matching [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) frontend renders team membership and per-worker streams out of the box. Follow the [Agent Service quickstart](/v2/deploy/agent-service#try-the-bundled-example) to boot both — once they are running, ask the leader agent to assemble a team and you will see it call `TeamCreate` / `AgentCreate` automatically, watch workers come online, and observe them exchange messages in the UI.
<Frame caption="A leader agent assembling a team and coordinating workers in the example web UI.">
<img src="https://mintcdn.com/agentscope-ai-786677c7/c8Op3M8_8-WXpeVH/images/team.gif?s=604f394f94cca0dbca8fdeee75a0f7ff" alt="Agent team coordination demo" width="1920" height="1080" data-path="images/team.gif" />
</Frame>
## Concepts
| Concept | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Team** | A persistent group of agent members owned by one user. A `TeamRecord` carries the team's identity (name, description) and its member list. |
| **Leader** | The session that created the team. Only the leader can add or remove members or end the team. |
| **Worker** | A session spawned as a team member. Workers run their own ReAct loop in their own session and inherit the leader's chat model + workspace context. |
| **Team message** | A message routed between members through the message bus. Delivered as a `HintBlock` wrapped in a `<team-message from="…">` tag so the recipient's LLM can disambiguate it from a regular user turn. |
## Usage
### Creating a team
The team feature is built into Agent Service — no extra configuration is required. When a user sends a task that benefits from multi-agent collaboration, the leader agent automatically uses the built-in team tools to assemble and coordinate a team of workers.
Out of the box, the leader agent can:
* **Create a team** with a name and description that frames the collaboration goal.
* **Spawn workers** by giving each a name, role description, and an initial task. Workers begin executing immediately upon creation.
* **Exchange messages** with workers to provide follow-up instructions or collect results.
* **Dissolve the team** when the task is complete, cleaning up all worker sessions.
Every worker runs concurrently in its own session with its own event stream, visible in the frontend UI alongside the leader's conversation. The leader orchestrates work by reading worker outputs and sending messages — all through the same chat interface.
By default, all workers share the same system prompt template and permission settings. To give different worker roles different capabilities — for example, a read-only explorer versus a full-access coder — register custom sub-agent templates as described in the next section.
### Custom sub-agent types
By default every worker spawned by `AgentCreate` uses the same built-in system prompt and permission context. In practice, different roles need different capability boundaries — an agent that only explores the codebase should not be able to modify files, while one that writes code needs full edit access. `SubAgentTemplate` solves this by letting you define reusable blueprints that the leader agent can choose from when creating workers.
#### Registering templates
Pass a list of `SubAgentTemplate` instances to `create_app` via the `sub_agent_templates` parameter:
```python
from agentscope.app import create_app, SubAgentTemplate
from agentscope.permission import PermissionContext, PermissionMode
app = create_app(
storage=storage,
message_bus=message_bus,
workspace_manager=workspace_manager,
sub_agent_templates=[
SubAgentTemplate(
type="explorer",
description=(
"Read-only agents specialized in exploration tasks. "
"Use this type when you need to investigate the "
"codebase without making any changes."
),
system_prompt_template="""You are {member_name}, an explorer \
agent in team '{team_name}' led by {leader_name}.
Team purpose: {team_description}
Your role: {member_description}
## Responsibilities
- Complete the exploration tasks assigned by the team leader.
- You are read-only: you may inspect files and the codebase, but \
you must never modify, create, or delete anything.
## Reporting
- Always report the task result back to {leader_name} using the \
TeamSay tool, whether the task succeeds or fails.""",
permission_context=PermissionContext(
mode=PermissionMode.EXPLORE,
),
),
],
)
```
#### Template fields
| Field | Required | Default | Description |
| ------------------------ | -------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `type` | Yes | — | Template identifier (e.g. `"explorer"`, `"coder"`). Becomes an enum value of the `subagent_type` parameter in `AgentCreate`. |
| `description` | Yes | — | Agent-readable description exposed in the `AgentCreate` tool schema so the leader can choose the appropriate type. |
| `system_prompt_template` | Yes | — | Python format string for the worker's system prompt. See [available placeholders](#system-prompt-placeholders) below. |
| `permission_context` | No | `PermissionContext()` | Permission context applied to the worker. Controls what the worker is allowed to do (e.g. `PermissionMode.EXPLORE` for read-only). |
| `context_config` | No | `ContextConfig()` | Context window configuration for the worker. |
| `react_config` | No | `ReActConfig()` | ReAct loop configuration for the worker. |
| `tasks_context` | No | `TaskContext()` | Pre-defined task context, allowing the template to seed an initial workflow. |
#### System prompt placeholders
The `system_prompt_template` string is formatted with these variables when a worker is created:
| Placeholder | Value |
| ---------------------- | ------------------------------------------------------ |
| `{team_name}` | The team's name as set by `TeamCreate`. |
| `{team_description}` | The team's description as set by `TeamCreate`. |
| `{member_name}` | The worker's name as set by `AgentCreate`. |
| `{member_description}` | The worker's role description as set by `AgentCreate`. |
| `{leader_name}` | The leader agent's display name. |
#### Runtime behavior
* **No custom templates registered** — `AgentCreate` does not expose a `subagent_type` parameter at all. All workers use the built-in default template. This keeps the tool schema clean when templates are not needed.
* **Custom templates registered** — `AgentCreate` automatically gains a `subagent_type` enum field listing all available types (including `"default"`). The leader agent sees each type's description and can choose which one to use.
* **Overriding the default** — registering a template with `type="default"` replaces the built-in default template entirely.
* **Uniqueness** — template type names must be unique. Duplicate types cause a `ValueError` at startup.
## Architecture
### Built-in tools
A leader session is automatically given these tools. Workers see only `TeamSay`.
| Tool | Purpose |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TeamCreate` | Create a new team rooted at the current session and become its leader. |
| `AgentCreate` | Spawn a new worker into the team with a name, role description, first task, and permission mode. The worker begins executing as soon as it is created. |
| `TeamSay` | Send a message to a named member (or broadcast). The recipient's session receives the message through its inbox and resumes on the next wakeup. |
| `TeamDelete` | Dissolve the team and clean up every member session. Only the leader can call this. |
### Coordination model
Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the [message bus](/v2/deploy/agent-service#resource-model) — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient's inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does.
Team communication reuses the same inbox + wakeup primitives the service uses for scheduled fires and background-tool completions:
1. The sender's tool call (`TeamSay`, `AgentCreate`'s initial prompt, …) pushes a `HintBlock` onto the recipient session's inbox via the message bus.
2. A wakeup is enqueued for the recipient.
3. The wakeup dispatcher running on any process picks up the wakeup and drives `ChatService.run` for that session.
4. `InboxMiddleware` drains the inbox before the next reasoning step, so the queued team messages land in the recipient's context as `HintBlockEvent`s.
This means workers run *concurrently* on the same service — they are not nested coroutines under the leader. The leader observes a worker's progress by reading its session stream, or by having the worker `TeamSay` back to it.
## See also
<CardGroup cols={2}>
<Card title="Agent Service" icon="server" href="/v2/deploy/agent-service">
The hosting layer that powers teams — sessions, message bus, workspace lifecycle.
</Card>
<Card title="Agent" icon="robot" href="/v2/building-blocks/agent">
The agent abstraction each team member runs.
</Card>
</CardGroup>

323
.claude/skills/agentscope-skill/references/v2-overview.md Normal file
View File

@ -0,0 +1,323 @@
<!-- AgentScope 2.0 官方文档收敛 · 概览篇 · 抓取2026-06-22自 docs.agentscope.io · 含: 2.0是什么/快速上手/变更日志/FAQ -->
<!-- ===== source: v2/index.md ===== -->
# What's AgentScope 2.0?
> More secure, more efficient, more flexible, and more complete agent development.
AgentScope 2.0 is a major update to our agent framework, with a focus on improving the developer experience and
making it easier to build and run agents in production.
<Note>
AgentScope 2.0 is a breaking change from 1.0, with significant improvements in the core abstractions,
APIs and architecture. We recommend users to migrate to 2.0 to take advantage of the new features and
improvements.
</Note>
2.0 brings the following major changes and improvements:
* **Event System**: Every step the agent takes — text, thinking, tool call, tool result — is observable as a typed stream, so you can render rich, responsive UIs and integrate with AG-UI or A2A without writing adapters.
* **Execution Security**: Dangerous tool calls can be denied or held for review, and untrusted code can run inside a sandbox — the agent never silently touches the host or leaks credentials.
* **Human-in-the-loop**: Users can confirm or edit tool arguments mid-run, and sensitive actions can be handed off to your own backend instead of executed in-process, with the agent resuming exactly where it paused.
* **More Efficient**: Multi-tool steps finish faster through concurrent execution, long conversations stay within the context window automatically, oversized tool outputs no longer blow up the prompt, and transient provider failures fall back gracefully.
* **Workspace System**: Move an agent from your laptop to a Docker host or an E2B sandbox by changing one line, with working directory, MCP clients and skills cleanly isolated per user, agent or session.
* **Agent Service**: Host any agent over REST + SSE with multi-tenant, multi-session concurrency, resumable streams, durable sessions, scheduled runs and managed credentials — without writing the service plumbing yourself.
If you are still evaluating whether to migrate, check out the [Changelog](/v2/change-log) for a full breakdown of every change — it should give you everything you need to plan your migration to AgentScope 2.0.
<CardGroup cols={2}>
<Card title="Event System" icon="wave-pulse" href="/v2/building-blocks/message-and-event">
Observe every step of the agent and stream it straight into your UI.
</Card>
<Card title="Execution Security" icon="shield-halved" href="/v2/building-blocks/permission-system">
Gate or sandbox dangerous tool calls before they touch the host.
</Card>
<Card title="Human-in-the-loop" icon="user-check" href="/v2/building-blocks/message-and-event">
Let users review and edit tool arguments before execution, or delegate sensitive actions to your own backend entirely.
</Card>
<Card title="Efficient Agent" icon="gauge-high" href="/v2/building-blocks/agent">
Tool calls are auto-batched and run concurrently or sequentially based on each tool's properties.
</Card>
<Card title="Workspace System" icon="cube" href="/v2/building-blocks/workspace">
Swap Local, Docker or E2B without rewriting the agent.
</Card>
<Card title="Agent Service" icon="server" href="/v2/deploy/agent-service">
Ship agents over REST + SSE with multi-tenant, multi-session concurrency, sessions, schedules and credentials.
</Card>
</CardGroup>
<!-- ===== source: v2/quickstart.md ===== -->
# Quickstart
> Get up and running with AgentScope 2.0 in minutes
## Installation
AgentScope requires Python 3.11+, and you can install it from PyPI or from source.
It's recommended to install AgentScope by using [uv](https://github.com/astral-sh/uv).
### From PyPI
```bash
uv pip install agentscope
```
### From Source
```bash
git clone -b main https://github.com/agentscope-ai/agentscope
cd agentscope
uv pip install -e .
```
### Verify Installation
To ensure AgentScope is installed successfully, check via executing the following code:
```python
import agentscope
print(agentscope.__version__)
```
## Your First Agent
The snippet below builds the minimal agent: a DashScope credential, the matching chat model, an empty toolkit, and an `Agent`. The agent exposes two entry points — `reply` returns the final message, while `reply_stream` yields incremental events as the agent reasons and acts.
```python
import asyncio
import os
from agentscope.agent import Agent
from agentscope.credential import DashScopeCredential
from agentscope.event import EventType
from agentscope.message import UserMsg
from agentscope.model import DashScopeChatModel
from agentscope.tool import Toolkit, Bash, Read, Write, Edit
async def main() -> None:
agent = Agent(
name="Friday",
system_prompt="You are a helpful assistant named Friday.",
model=DashScopeChatModel(
credential=DashScopeCredential(
api_key=os.getenv("DASHSCOPE_API_KEY"),
),
model="qwen-plus",
),
toolkit=Toolkit(tools=[Bash(), Read(), Write(), Edit()]),
)
user_msg = UserMsg(name="user", content="Hello, who are you?")
# Option 1: await the final assistant message.
reply_msg = await agent.reply(user_msg)
# `reply_msg` is an `AssistantMsg` whose `content` is a list of blocks.
# Inspect text blocks, tool calls, etc. as needed.
...
# Option 2: stream incremental events (text deltas, tool calls, ...).
async for event in agent.reply_stream(user_msg):
# Dispatch on `event.type` — each branch handles one event kind.
match event.type:
case EventType.TEXT_BLOCK_DELTA:
# Streaming text chunk from the model — append to UI / stdout.
...
case EventType.TOOL_CALL_START:
# The agent is about to invoke a tool — surface the call.
...
case _:
# Other events: thinking blocks, tool results, reply end, ...
...
asyncio.run(main())
```
<Tip>
Set `DASHSCOPE_API_KEY` in your environment before running the script. To use a different provider, swap `DashScopeCredential` and `DashScopeChatModel` for the matching pair (e.g. `OpenAICredential` and `OpenAIChatModel`).
</Tip>
## Extra Dependencies
To satisfy the requirements of different functionalities, AgentScope provides extra dependencies that can be installed based on your needs.
* **full**: including extra dependencies for model APIs, tool functions and more.
* **dev**: development dependencies, including testing and documentation tools.
For example, when installing the full dependencies, the installation command varies depending on your operating system.
* For Windows users:
```bash
uv pip install agentscope[full]
```
* For Mac and Linux users:
```bash
uv pip install agentscope\[full\]
```
<!-- ===== source: v2/change-log.md ===== -->
# Changelog
> Core differences between AgentScope 2.0 and 1.0
AgentScope 2.0 is a breaking release. The notes below summarize the differences against 1.0, grouped by module.
## Agent
* Refactor `ReActAgent` into a new unified `Agent` class implementation.
* Replace the `__call__` method in 1.0 with the `reply_stream` and `reply` public methods.
* Support yielding agent events from `reply_stream` for richer observability and control.
* Support **permission checks** and **human-in-the-loop** confirmations through the event stream.
* Support offloading the compressed context and oversized tool results via a new `Offloader` interface.
* Deprecate the hook mechanism and replace it with a new agent middleware system.
* Deprecate the `state_dict` and `load_state_dict` methods, moving towards explicit state management through the new `AgentState` type.
* Deprecate the `print` interface of the agent class, turning the agent into a pure producer.
* Deprecate the OpenTelemetry integration within the agent class and leave it to a new middleware implementation.
## Event <Badge color="green" size="sm">New</Badge>
* Add event system for better frontend integration and human-in-the-loop support.
## Message
Content blocks refactor:
* Refactor all content blocks by inheriting from the Pydantic `BaseModel` for better validation, serialization, and extensibility.
* Refactor `ImageBlock`, `AudioBlock`, `VideoBlock` into a unified `DataBlock` with a `media_type` field for extensibility.
* Add `HintBlock` for agent guidance and intermediate reasoning.
* Rename `ToolUseBlock` to `ToolCallBlock`.
* Add `state` and `suggested_rules` fields to `ToolCallBlock` for richer tool-call lifecycle modeling.
* Add `state` field to `ToolResultBlock` for richer tool-call lifecycle modeling.
* Add `id` field for all blocks for better traceability and referencing.
`Msg` class refactor:
* Refactor `Msg` to inherit from `BaseModel` and enforce content validation.
* Add `created_at`, `finished_at`, and `usage` fields to the `Msg` class for better observability and accounting.
* Add `append_event` method to `Msg` for yielding events from the agent's reply stream.
* Add factory methods `UserMsg`, `AssistantMsg`, and `SystemMsg` to create messages with the appropriate role.
* Add `content` field constraints with the specified `role` types.
## Permission <Badge color="green" size="sm">New</Badge>
* Add a new permission system for gating tool execution, human-in-the-loop confirmation, and overall agent autonomy control.
## Tool
* Add `ToolBase` abstraction for all tools.
* Refactor built-in tools:
* Add `Bash`, `Edit`, `Glob`, `Grep`, `Read`, and `Write` with permission control.
* Add `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` for task management.
`Toolkit` refactor:
* Support tools, skills, MCPs, and tool groups as first-class citizens in the `Toolkit` abstraction.
* Add `ToolGroup` for on-demand activation, with the reserved `basic` group always active.
* Add the `ResetTools` meta-tool for the agent to switch tool groups at runtime.
* Add `MCPTool` and `FunctionTool` adapters for uniform tool registration.
## MCP
* Refactor MCP implementation into a single `MCPClient` class for a unified client surface.
* Add `StdioMCPConfig` and `HttpMCPConfig` declarative configuration types for typed MCP setup.
## Skill <Badge color="green" size="sm">New</Badge>
* Add skill loader abstraction to support in-time skill loading from the filesystem/sandbox/web.
* Add `LocalSkillLoader` class to support directory-based skill loading and monitoring.
* Support packaging skills into `ToolGroup`s for on-demand activation and better organization.
## Workspace <Badge color="green" size="sm">New</Badge>
* Add the workspace abstraction supplying tools, MCPs, skills, and context offloading through one unified interface.
* Add `LocalWorkspace`, `DockerWorkspace`, and `E2BWorkspace` implementations sharing the same agent-facing API for swappable execution backends.
* Add the `Offloader` protocol consumed by `Agent` for context compression and oversized tool-result handling.
* Add `LocalWorkspaceManager`, `DockerWorkspaceManager`, and `E2BWorkspaceManager` with **agent-level isolation** for multi-tenant services.
* Add an in-workspace **MCP gateway** so host-side agents can reach MCP servers running inside containers and sandboxes.
## Model
* Decouple credential management from the model classes and centralize it in a new `Credential` module.
* Support credential-aware model listing and retrieval.
* Support Kimi, Moonshot, DeepSeek, XAI, and OpenAI Response API.
* Integrate formatter into the chat model abstraction and support default formatters for different model providers.
* Add the `ModelCard` schema describing model identity, capabilities, and parameter overrides.
* Add class method `list_models` for frontend model listing and selection.
* Deprecate the `Trinity` model wrapper.
## Middleware <Badge color="green" size="sm">New</Badge>
* Refactor the hook mechanism into a more general agent middleware system.
* Add `TracingMiddleware` as the new entry point for OpenTelemetry tracing, replacing the in-agent integration.
## Agent Service <Badge color="green" size="sm">New</Badge>
* Add a new FastAPI-based agent service and sandbox support in the `app` module.
* Add the `create_app` FastAPI factory exposing agent, chat, model, credential, session, schedule, workspace, and background-task routers.
* Add lifespan-scoped `SessionManager`, `SchedulerManager`, `BackgroundTaskManager`, and workspace managers for multi-tenant resource allocation.
* Add `AGUIProtocolMiddleware` for streaming and `ToolOffloadMiddleware` for oversized payloads.
* Add Redis-backed storage.
## Memory
* Deprecate the memory module in 2.0 due to its tight coupling with agent logic.
## RAG & Long-Term Memory
* Unify RAG and long-term memory into one module.
* Migration from 1.0 to 2.0 is in progress; the module — knowledge bases, document readers, and stores — will return on top of the 2.0 architecture in upcoming releases.
<!-- ===== source: v2/others/faq.md ===== -->
# FAQ
> Frequently asked questions about AgentScope v2.0
<AccordionGroup>
<Accordion title="Is AgentScope 2.0 compatible with 1.0?">
No. AgentScope 2.0 is a breaking release that introduces a redesigned agent abstraction, a new event system, the workspace and permission systems, and many other new features. APIs are not source-compatible with 1.0, and there is no automatic migration path.
We recommend upgrading to 2.0 for all new projects to benefit from the new capabilities. The 1.0 documentation remains available for existing users.
</Accordion>
<Accordion title="Does AgentScope support sandboxed execution?">
Yes. The **workspace** abstraction is AgentScope's execution environment for agents and ships three implementations — `LocalWorkspace` (host filesystem), `DockerWorkspace` (container), and `E2BWorkspace` (E2B cloud sandbox) — sharing the same interface so the same agent code runs against any backend. Workspaces also own MCP server lifecycles, skill management, and context offloading.
See [Workspace](/v2/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`.
</Accordion>
<Accordion title="Is there a frontend for AgentScope 2.0?">
Yes, on two layers:
* **TypeScript SDK** — install with `pnpm install @agentscope-ai/agentscope`. It mirrors the Python `Msg` and `Event` types so frontend code can consume agent streams without re-implementing the protocol.
* **Frontend UI** — a ready-to-use web app for [Agent Service](/v2/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code.
</Accordion>
<Accordion title="Will RAG and long-term memory return in 2.0?">
Yes. Both modules are being ported from 1.0 to the 2.0 architecture and will land in upcoming releases. Track the changelog and GitHub releases for availability.
</Accordion>
<Accordion title="Are there language bindings other than Python?">
Yes. AgentScope is available in three languages, each with its own repository:
* **Python** — [`agentscope-ai/agentscope`](https://github.com/agentscope-ai/agentscope) (this documentation)
* **TypeScript** — [`agentscope-ai/agentscope-typescript`](https://github.com/agentscope-ai/agentscope-typescript)
* **Java** — [`agentscope-ai/agentscope-java`](https://github.com/agentscope-ai/agentscope-java)
</Accordion>
</AccordionGroup>