Commit b60be546 by Archer Committed by GitHub

perf: improve Sandbox timeouts and update 4.16.0 documentation (#7438)

* perf: timeout and doc

* fix(docs): use valid dotenv code fence
parent f732bc52
---
title: 'V4.16.0-beta1 (In Progress)'
description: 'FastGPT V4.16.0-beta1 Release Notes'
description: 'FastGPT V4.16.0-beta1 release notes'
---
## 📦 Upgrade Guide
### 1. Migrate Agent Sandbox Data
### 1. Update the Agent Sandbox configuration
This release changes App Chat Agent Sandboxes from one instance per chat to one shared instance per App and user. Files from different chats remain separated in the `sessions/<chatId>` directory, while published Skills are stored in the shared `projects` directory.
Environments that enable Agent Sandbox must add a browser-accessible preview proxy URL to both `fastgpt-app` and `fastgpt-pro`:
If Agent Sandbox was enabled in your deployment, complete the legacy Workspace migration after upgrading. Deployments that never enabled Agent Sandbox can skip this section.
```dotenv
# HTTP(S) URL used by browsers to preview Sandbox files
AGENT_SANDBOX_PREVIEW_PROXY_URL=https://sandbox-proxy.example.com
```
After updating FastGPT and the supporting Agent Sandbox services, run the new endpoint in dry-run mode. It reports pending beta6 Sandbox field normalization and legacy Skill Debug Chat cleanup without creating resources, accessing object storage, or modifying data:
The URL must start with `http://` or `https://`. With a default single-port deployment, it can point to the same host and port as `AGENT_SANDBOX_PROXY_URL`, while the protocols remain HTTP(S) and WebSocket(S), respectively.
```bash
curl -X POST 'https://your-domain/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: YOUR_ROOT_KEY' \
-d '{"dryRun":true}'
```
We strongly recommend using a different origin for the preview URL and the main FastGPT site. Sandbox HTML may contain user-generated scripts; serving it from the same origin would place those scripts inside the main site's same-origin security boundary, where they could access site credentials or APIs. FastGPT does not currently enforce origin isolation.
After reviewing the dry-run result, run the migration. The formal run performs beta6 normalization first and continues to Workspace archiving in the same request only when the remaining count reaches `0`:
The preview URL is a short-lived, read-only bearer capability. It authorizes access to the entire Sandbox Workspace, not just the individual file in the URL. Anyone with the link can change the URL path during its validity period and read other files in the same Sandbox Workspace. Do not share it with users who should not access that Workspace.
```bash
curl -X POST 'https://your-domain/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: YOUR_ROOT_KEY' \
-d '{"dryRun":false}'
```
The following optional settings are also available:
| Variable | Default | Description |
| ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENT_SANDBOX_CPU_COUNT` | `1` | Maximum CPU cores per Agent Sandbox instance. |
| `AGENT_SANDBOX_MEMORY_MIB` | `2048` | Memory limit per Agent Sandbox instance, in MiB. |
| `AGENT_SANDBOX_STORAGE_SIZE_GI` | `1` | Agent Sandbox storage capacity, in Gi. Used as the Sealos Devbox storage limit and to create new PVCs in OpenSandbox Kubernetes mode. |
| `AGENT_SANDBOX_SUSPEND_MINUTES` | `60` | Number of minutes an active Sandbox can remain idle before it is automatically suspended. |
| `AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS` | `7` | Number of days a suspended Sandbox can remain inactive before it is automatically archived. |
The migration first runs the complete V4.15.0-beta6 prerequisites. It backfills legacy Sandbox `sourceType/sourceId`, removes legacy fields, deletes orphan resources, and cleans legacy Skill Debug Chat rows and old prefixes from both private and public buckets. Skills whose IDs conflict with App IDs are excluded from Chat cleanup. The script then combines the remaining Sandbox and Debug Chat counts into `normalization.pendingCount`; Workspace archiving starts only when that value is `0`. It then archives every legacy Workspace and removes old compute resources, migrates Skills, and finally consolidates App data into user-level Sandboxes by App and user. If any archive operation fails, installation does not start. Each new Sandbox is stopped after its Workspace is installed and starts through the normal lifecycle on first use. The script is safe to retry: completed archive and migration work is not repeated, and legacy archives and MongoDB records remain available as backups after migration.
The E2B Sandbox Provider has been removed. Environments previously configured for E2B must switch to `opensandbox` or `sealosdevbox` and remove `AGENT_SANDBOX_E2B_API_KEY`.
Check `normalization.pendingCount`, `normalizationBlocked`, `failedCount`, and `failures` in the response. The migration is complete only when both `normalization.pendingCount` and `failedCount` are `0`, and `normalizationBlocked` is `false`.
> The preview protocol has changed for FastGPT, `fastgpt-agent-sandbox-proxy`, and `fastgpt-agent-sandbox`. When Agent Sandbox is enabled, use the images released with this version. Mixing old and new versions is not supported.
### 2. Update Agent Sandbox Configuration
### 2. Update the Agent Sandbox Proxy environment variables
Deployments with Agent Sandbox enabled must add a browser-accessible preview proxy URL to both `fastgpt-app` and `fastgpt-pro`:
Version 4.16.0 requires the proxy for static resource access. If your gateway supports WebSocket and HTTP traffic on the same port, you only need to expose one port. Otherwise, set `PREVIEW_PORT` to configure the HTTP port.
```dotenv
# Browser-accessible HTTP(S) URL for Sandbox file previews
AGENT_SANDBOX_PREVIEW_PROXY_URL=https://sandbox-proxy.example.com
# Port for the WebSocket and HTTP services
PORT=1006
# HTTP service port; overrides PORT when set
PREVIEW_PORT=1007
```
The URL must use either the `http://` or `https://` prefix. In a default single-port deployment, the `AGENT_SANDBOX_PROXY_URL` host and port can also serve previews, with HTTP(S) used for previews and WebSocket(S) used for the editor connection.
### 3. Migrate Agent Sandbox data
This release changes App Chat's Agent Sandbox from “one instance per conversation” to “one shared instance per App and user.” Files from different conversations remain isolated under `sessions/<chatId>`. Published Skills are stored in the shared `projects` directory.
We strongly recommend using an origin separate from the FastGPT application for previews. Sandbox HTML may contain user-generated scripts. A same-origin deployment places those scripts inside the application's same-origin security boundary, where they may be able to access application credentials or APIs. FastGPT does not currently enforce origin isolation.
If Agent Sandbox was previously enabled, migrate the existing Workspaces in the following order. You can skip this section if Agent Sandbox has never been enabled.
A preview URL is a temporary, read-only bearer capability and is not limited to the file named in the URL. Anyone with the URL can change its path to read other files in the same Sandbox Workspace while it remains valid. Do not share it with anyone who should not have access to that Workspace.
Run a dry run first to see how many beta6 Sandbox fields require normalization and how many legacy Skill Debug Chats require cleanup. The dry run does not create resources, access object storage, or modify data:
This release also adds the following optional settings:
```bash
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
```
| Variable | Default | Description |
| ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `AGENT_SANDBOX_CPU_COUNT` | `1` | CPU core limit for each Agent Sandbox instance. |
| `AGENT_SANDBOX_MEMORY_MIB` | `2048` | Memory limit for each Agent Sandbox instance, in MiB. |
| `AGENT_SANDBOX_STORAGE_SIZE_GI` | `1` | Agent Sandbox storage size in Gi. Used as the Sealos Devbox storage limit and for new OpenSandbox PVCs in Kubernetes mode. |
| `AGENT_SANDBOX_SUSPEND_MINUTES` | `60` | Minutes of inactivity before a running Sandbox is stopped. |
| `AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS` | `7` | Days of inactivity before a stopped Sandbox is archived. |
After reviewing the dry-run result, run the migration:
```bash
curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
```
The E2B Sandbox Provider has been removed. Deployments previously using E2B must switch to `opensandbox` or `sealosdevbox` and remove the `AGENT_SANDBOX_E2B_API_KEY` environment variable.
The migration first runs all V4.15.0-beta6 normalization steps. It fills in `sourceType/sourceId` for legacy Sandboxes, removes obsolete fields, deletes orphaned resources that cannot be associated, and cleans up the three legacy Skill Debug Chat collections and old private/public Bucket prefixes when `sourceType` is missing. After recounting, the two categories are combined into `normalization.pendingCount`; Workspace archiving does not begin while the count is non-zero. Once normalization is complete, all legacy Workspaces are archived, old compute resources are cleaned up, Skills are migrated, and records are aggregated into user-level Sandboxes by App and user. Installation does not start if any archive operation fails. New Sandboxes are suspended after Workspace installation and start normally on first use. The script is safe to retry: completed archive and migration operations are not repeated. Old archives and MongoDB records are retained as backups after migration.
> The preview protocol has changed across FastGPT and the `fastgpt-agent-sandbox-proxy` and `fastgpt-agent-sandbox` services. If Agent Sandbox is enabled, use the matching images for this release. Mixed-version deployments are not supported.
Check `normalization.pendingCount`, `normalizationBlocked`, `failedCount`, and `failures` in the response. The migration is complete only when `normalization.pendingCount` and `failedCount` are both `0` and `normalizationBlocked` is `false`.
### 3. Migrate Manual HTTP Tool Schemas
### 4. Migrate manual HTTP tool data
This release converts array parameters in manually configured HTTP tools to standard JSON Schema. Deployments with manual HTTP tools created before this upgrade must run this migration. OpenAPI-based HTTP tools do not require migration and are skipped automatically.
This release changes array parameters in manually configured HTTP tools to standard JSON Schema. Environments with manual HTTP tools created before the upgrade must run this migration. OpenAPI-mode HTTP tools do not require migration and are skipped automatically.
First, run a dry run to inspect pending data in current Apps and historical versions. A dry run does not modify data:
Run a dry run first to inspect pending data in current Apps and historical versions. The dry run does not modify data:
```bash
curl -X POST 'https://your-domain/api/admin/4160/initHttpToolSchema' \
curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: YOUR_ROOT_KEY' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":true}'
```
After reviewing the result, run the migration:
After confirming the result, run the migration:
```bash
curl -X POST 'https://your-domain/api/admin/4160/initHttpToolSchema' \
curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: YOUR_ROOT_KEY' \
-H 'rootkey: 你的ROOT_KEY' \
-d '{"dryRun":false}'
```
The script first selects HTTP tool Apps by type, then migrates historical versions matching those App IDs. It only processes manual configurations where `apiSchemaStr` is absent; other Apps and OpenAPI-based tools remain unchanged. The migration runs in batches and is safe to retry. `total.changedDocumentCount` reports the number of documents requiring migration. After the formal run, run another dry run and confirm that this value is `0`.
The script first filters Apps by HTTP tool type, then migrates historical versions associated with those `appId` values. Only manual-mode tools without `apiSchemaStr` are processed; other Apps and OpenAPI-mode tools are left unchanged. The migration runs in batches and is safe to retry. `total.changedDocumentCount` in the response shows how many documents require processing. Run another dry run after the migration and confirm that this value is `0`.
## 🚀 New Features
## 🚀 New
1. Agent Sandbox now uses App-level, per-user instances. Chats for the same App and user reuse one Sandbox while keeping chat files in separate session directories.
2. Sandbox HTML and files can now be previewed through short-lived, read-only URLs without uploading a duplicate copy to object storage.
3. App Workflows now archive and restore their Workspace automatically when the Sandbox Provider or runtime image changes, completing the upgrade within the current run.
4. Workflow tool nodes can now have selected input parameters generated by the Agent while preserving existing fixed-value, reference, and user-input settings.
5. When ChatAgent selects a tool, each parameter can be explicitly marked as AI-generated.
6. Knowledge Base data now supports custom `metadata`. JSON metadata can be imported through the API or CSV templates and is preserved in search results and backup exports. CSV templates only allow `q`, `a`, `index`, and `metadata` headers; `q`, `a`, and `metadata` must each appear once, while `index` may appear multiple times in any order.
1. Agent Sandbox now runs at the App-user level. Multiple conversations from the same user and App share a Sandbox while keeping files isolated in separate session directories.
2. Sandbox HTML and files can be previewed directly through short-lived, read-only links without being uploaded to object storage again.
3. App Workflow automatically archives and restores Workspaces when the Sandbox Provider or runtime image changes. The upgrade completes silently during the current run.
4. Workflow tool nodes can delegate selected input parameters to the Agent for generation while preserving fixed values, references, and user inputs.
5. ChatAgent tool selection supports explicitly choosing whether parameters should be generated by AI.
6. Knowledge Base data supports custom `metadata`, which can be imported as JSON through the API or CSV template. Search results and backup exports preserve this field. CSV templates only allow `q`, `a`, `index`, and `metadata` headers; `q`, `a`, and `metadata` each use one column, while `index` may use multiple columns in any order.
7. Large-file chunked uploads.
## ⚙️ Improvements
1. Reworked Agent Sandbox lifecycle and migration handling so create, stop, archive, restore, delete, and Provider-switch operations have concurrency protection, resumable progress, and idempotent retries.
2. App Chat now disables Sandbox capabilities gracefully when Sandbox is unavailable or unsupported by the current team plan, while other models, tools, Knowledge Bases, and Workflow nodes continue to run.
3. OpenSandbox persistent volumes can be preserved after compute resources stop and reused on the next run. Stop and archive thresholds are now configurable.
4. Unified runtime image upgrade status for Apps and Skills, with continuous upgrade polling in the Skill editor.
5. Sandbox file writes now create missing parent directories automatically.
6. Improved compatibility for legacy Workflow data and tool parameters.
1. Refactored the Agent Sandbox lifecycle and migration flow with concurrency protection, resumable execution, and idempotent retries for creation, suspension, archiving, restoration, deletion, and Provider changes.
2. When Agent Sandbox is unavailable or unsupported by the current team plan, App Chat disables Sandbox automatically. Other models, tools, Knowledge Bases, and Workflow nodes remain available.
3. OpenSandbox can retain persistent volumes after stopping and reuse them on later runs. Suspension and archive thresholds can be configured through environment variables.
4. App and Skill now share runtime image upgrade status, and the Skill editor can continuously poll for upgrade results.
5. Sandbox file writes now create parent directories automatically, preventing failures when writing to nested paths.
6. Improved compatibility handling for legacy Workflow data and tool parameters.
## 🐛 Fixes
1. Fixed OpenSandbox resources not being released or reused correctly after stopping.
2. Fixed state races and duplicate operations during Agent Sandbox creation, restore, and runtime upgrades.
3. Fixed Sandbox writes to nested paths failing when parent directories did not exist.
4. Fixed number inputs becoming plain text fields after switching between AI-generated and manual input modes.
5. Fixed string text inputs being incorrectly rendered as select menus.
6. Fixed the JSON Editor being incorrectly included in Workflow tool configuration.
7. Fixed tool execution errors being incorrectly displayed in Agent and Workflow tool interfaces.
2. Fixed state races and duplicate operations during Agent Sandbox creation, restoration, and runtime upgrades.
3. Fixed Sandbox writes to nested directories failing when the parent directory did not exist.
4. Fixed number inputs becoming regular text fields after switching between Agent-generated and manual input.
5. Fixed string inputs being rendered incorrectly as dropdowns.
6. Fixed JSON Editor being incorrectly included in Workflow tool configuration.
7. Fixed tool execution errors being displayed incorrectly in Agent and Workflow tool interfaces.
8. Fixed uninstalled tools still appearing in the system tool list.
9. Fixed the default version selection for Agent and Agent V2 so it uses the latest version.
9. Fixed the default Agent/Agent V2 version selection so it chooses the latest version by default.
10. Fixed images embedded in S3-hosted files with spaces failing to parse because of malformed keys and returning 404 errors.
## 🛠️ Code Improvements
1. Split Sandbox Adapter responsibilities into lifecycle, filesystem, command execution, and Provider contracts, and removed the E2B Adapter.
2. Added direct Workspace previews, Range requests, path-escape protection, and session authentication to Agent Sandbox Proxy and IDE Agent.
3. Refined Workflow schemas to unify tool calls and form rendering.
1. Split Sandbox Adapter by lifecycle, filesystem, command execution, and Provider contracts, and removed the E2B Adapter.
2. Added direct Workspace preview, Range requests, path traversal protection, and session authentication to Agent Sandbox Proxy and IDE Agent.
3. Optimized Workflow schemas and unified tool calls with form rendering.
4. Extended tool JSON Schema support for additional data types.
5. Unified service file-read timeouts.
......@@ -34,7 +34,18 @@ E2B Sandbox Provider 已移除。此前配置过 E2B 的环境需要切换为 `o
> FastGPT、`fastgpt-agent-sandbox-proxy` 和 `fastgpt-agent-sandbox` 的预览协议已同步变更。启用 Agent Sandbox 时必须使用本版本配套镜像,不支持新旧版本混合部署。
### 2. 迁移 Agent Sandbox 数据
### 2. 更新 Agent-sandbox-proxy 环境变量
4.16.0 需要依赖 proxy 进行静态资源代理访问,如果网关支持 ws 和 http 在同一个端口,则可以只开放一个端口。如果不支持,可以通过设置 `PREVIEW_PORT` 来设置 http 访问端口。
```dotenv
# ws和http服务的端口
PORT=1006
# http服务的端口,可以覆盖 PORT
PREVIEW_PORT=1007
```
### 3. 迁移 Agent Sandbox 数据
本版本将 App Chat 的 Agent Sandbox 从“每个对话一个实例”调整为“同一 App、同一用户共享一个实例”。不同对话的文件仍分别保存在 `sessions/<chatId>` 目录中,已发布 Skill 则统一保存在共享的 `projects` 目录中。
......@@ -62,7 +73,7 @@ curl -X POST 'https://你的域名/api/admin/4160/initUserSandbox' \
请检查返回结果中的 `normalization.pendingCount`、`normalizationBlocked`、`failedCount` 和 `failures`。只有 `normalization.pendingCount` 和 `failedCount` 均为 `0`,且 `normalizationBlocked` 为 `false` 时,才表示本次迁移全部完成。
### 3. 迁移手动 HTTP 工具 Schema
### 4. 迁移手动 HTTP 工具数据
本版本将手动模式 HTTP 工具的数组参数改为标准 JSON Schema。升级前创建过手动 HTTP 工具的环境需要执行此迁移;OpenAPI 模式的 HTTP 工具无需迁移,脚本会自动跳过。
......@@ -94,6 +105,7 @@ curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
4. 工作流工具节点支持将指定输入参数交由 Agent 自动生成,并保留固定值、引用和用户输入等既有配置。
5. ChatAgent 选择工具时,支持手动指定是否为 AI 生成参数。
6. 知识库数据支持自定义 `metadata`,可通过 API 或 CSV 模板导入 JSON 元数据;检索结果和备份导出会保留该字段。CSV 模板仅允许 `q`、`a`、`index`、`metadata` 表头,`q`、`a`、`metadata` 各一列,`index` 可多列且顺序任意。
7. 大文件分块上传。
## ⚙️ 优化
......@@ -115,6 +127,7 @@ curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
7. 修复工具运行错误在 Agent/工作流工具界面中被错误展示的问题。
8. 修复系统工具列表中已卸载工具的展示问题。
9. 修复 Agent/Agent V2 默认版本选择逻辑,使其默认选择最新版本。
10. S3 文件如果有空格时,解析其文件内的图片,会因 key 异常 404。
## 🛠️ 代码优化
......@@ -122,3 +135,4 @@ curl -X POST 'https://你的域名/api/admin/4160/initHttpToolSchema' \
2. Agent Sandbox Proxy 和 IDE Agent 增加 Workspace 直连预览、Range 请求、路径逃逸防护及会话鉴权。
3. 工作流 schema 优化,统一工具调用和表单渲染。
4. 扩展工具 JSON Schema,支持更多数据类型。
5. 统一服务文件读取超时时间。
......@@ -329,8 +329,10 @@
"content/self-host/upgrading/4-15/4154.mdx": "2026-07-30T11:22:58+08:00",
"content/self-host/upgrading/4-15/4155.en.mdx": "2026-07-30T11:22:58+08:00",
"content/self-host/upgrading/4-15/4155.mdx": "2026-07-30T11:22:58+08:00",
"content/self-host/upgrading/4-16/41601.en.mdx": "2026-07-30T16:03:06+08:00",
"content/self-host/upgrading/4-16/41601.mdx": "2026-07-30T16:03:06+08:00",
"content/self-host/upgrading/4-15/4156.en.mdx": "2026-07-31T17:46:31+08:00",
"content/self-host/upgrading/4-15/4156.mdx": "2026-07-31T17:46:31+08:00",
"content/self-host/upgrading/4-16/41601.en.mdx": "2026-08-03T17:31:52+08:00",
"content/self-host/upgrading/4-16/41601.mdx": "2026-08-03T17:31:52+08:00",
"content/self-host/upgrading/outdated/40.en.mdx": "2026-07-25T00:27:20+08:00",
"content/self-host/upgrading/outdated/40.mdx": "2026-07-25T00:27:20+08:00",
"content/self-host/upgrading/outdated/41.en.mdx": "2026-07-25T00:27:20+08:00",
......@@ -471,6 +473,6 @@
"content/self-host/upgrading/outdated/499.mdx": "2026-05-07T15:06:40+08:00",
"content/self-host/upgrading/upgrade-intruction.en.mdx": "2026-04-26T21:08:47+08:00",
"content/self-host/upgrading/upgrade-intruction.mdx": "2026-04-26T21:08:47+08:00",
"content/toc.en.mdx": "2026-07-29T19:55:49+08:00",
"content/toc.mdx": "2026-07-29T19:55:49+08:00"
"content/toc.en.mdx": "2026-07-31T17:46:31+08:00",
"content/toc.mdx": "2026-07-31T17:46:31+08:00"
}
\ No newline at end of file
......@@ -98,7 +98,7 @@ const NavBar = ({ currentTab }: { currentTab: TabEnum }) => {
maxW={['45vw', '280px']}
className="textEllipsis"
>
{datasetDetail.name}
{t('common:back')}
</Box>
</MyTooltip>
</Flex>
......
......@@ -27,4 +27,6 @@ export const putUpdateHttpTool = (data: UpdateHttpToolsBodyType) =>
PUT<UpdateHttpToolsResponseType>('/core/app/httpTools/update', data);
export const postRunHTTPTool = (data: RunHttpToolBodyType) =>
POST<RunHttpToolResponseType>('/core/app/httpTools/runTool', data);
POST<RunHttpToolResponseType>('/core/app/httpTools/runTool', data, {
timeout: 600000
});
......@@ -23,7 +23,7 @@ export const getMCPTools = (data: GetMcpToolsBodyType) =>
POST<GetMcpToolsResponseType>('/core/app/mcpTools/getTools', data);
export const postRunMCPTool = (data: RunMcpToolBodyType) =>
POST<RunMcpToolResponseType>('/core/app/mcpTools/runTool', data, { timeout: 300000 });
POST<RunMcpToolResponseType>('/core/app/mcpTools/runTool', data, { timeout: 600000 });
export const getMcpChildren = (data: GetMcpChildrenQueryType) =>
GET<GetMcpChildrenResponseType>('/core/app/mcpTools/getChildren', data);
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment