diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5176454b..1f45254e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,7 +12,7 @@ jobs: test: runs-on: ubuntu-latest env: - KSADK_WEB_VERSION: "0.2.18" + KSADK_WEB_VERSION: "0.2.19" steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml index c6fdf226..5b0335b5 100644 --- a/.github/workflows/publish-pypi.yml +++ b/.github/workflows/publish-pypi.yml @@ -9,7 +9,7 @@ on: ksadk_web_version: description: KsADK Web npm version to bundle required: false - default: "0.2.18" + default: "0.2.19" approved_source_commit: description: Reviewed source commit SHA recorded in docs/maintainer-approval-record.md required: false @@ -37,7 +37,7 @@ jobs: environment: name: pypi env: - KSADK_WEB_VERSION: ${{ github.event.inputs.ksadk_web_version || '0.2.18' }} + KSADK_WEB_VERSION: ${{ github.event.inputs.ksadk_web_version || '0.2.19' }} KSADK_APPROVED_SOURCE_COMMIT: ${{ github.event.inputs.approved_source_commit || vars.KSADK_APPROVED_SOURCE_COMMIT }} PUBLISH_TARGET: ${{ github.event.inputs.publish_target || 'full' }} permissions: diff --git a/CHANGELOG.md b/CHANGELOG.md index 29c0d9b2..f93fe3af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ - ADK Runner 接入 `ResumabilityConfig`、`invocation_id` 映射、递增 checkpoint、恢复审计和 runtime capability 描述；新增 `KSADK_ADK_RESUMABLE` 显式开关。 - TUI 新增 `/tools` 命令、模型选择、输入排队、处理中耗时状态、终端背景自适应和 `/clear` 原生 scrollback 清理。 - 新增 PostgreSQL 会话故障恢复 E2E 校验脚本，覆盖 LangGraph、LangChain、ADK、可读视图以及数据库中断后恢复写入。 +- 公开 Fumadocs 文档站新增中英文云端部署指南，覆盖云账号配置、`launch`、`build`/`deploy`、Code/Container、KCE、VPC、持久化存储、运行时 env 和部署验证；GitHub Pages 子路径下的静态搜索索引改为显式寻址。 ### 变更 @@ -46,7 +47,7 @@ - 修复 PostgreSQL 恢复后，降级期间创建的 session 无法继续写入 PG 的问题。 - 修复 ADK session 在健康 PostgreSQL 下不刷新其他副本新增事件的问题。 - 修复 DeepAgents 测试 fake model 对空内容 tool call 不产生 stream chunk 的兼容问题。 -- 修复 `langchain.agents.create_agent()` 返回 message-state 时，LangChain Runner 丢弃流式文本、思考过程和工具调用/结果并回退为同步执行的问题。 +- 修复 `langchain.agents.create_agent()` 返回 message-state 时，LangChain Runner 丢弃流式文本、思考过程和工具调用/结果并回退为同步执行，以及将 `Command(update=...)` 内部控制对象误作最终正文的问题。 - 修复 Windows Python 3.13 安装 ADK extra 时可能从源码构建 LiteLLM 并因缺少 MSVC linker 失败的问题；显式使用 `LiteLlm` 的用户可先安装官方二进制 wheel。 - 修复 coding profile 未直接暴露 workspace 写文件工具，导致新建文件绕行 dispatcher；同时明确 read/edit 必须串行并让无效编辑参数优先返回准确诊断。 - 修复本地 `agentengine web` 缺少 `ListSessionMessages` action，导致刷新或切换 session 后历史消息无法回显的问题；历史投影保留正文、思考、工具、审批和附件信息。 diff --git a/README.en.md b/README.en.md index 4f150f3b..73969840 100644 --- a/README.en.md +++ b/README.en.md @@ -53,7 +53,7 @@ Most agent frameworks solve how to build agents. KsADK solves how to run, debug, ## Architecture -

KsADK Agent Runtime Platform architecture

+

KsADK Agent Runtime Platform architecture

## Docs And Examples @@ -63,6 +63,7 @@ Most agent frameworks solve how to build agents. KsADK solves how to run, debug, - Architecture: - Ecosystem Positioning: - Observability: +- Cloud Deployment: - Samples: ## Related Projects diff --git a/README.md b/README.md index 23a8d39b..bdb6386c 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ agentengine web . --no-open ## 架构 -

KsADK Agent Runtime Platform 架构

+

KsADK 智能体运行时平台架构

## 文档与样例 @@ -63,6 +63,7 @@ agentengine web . --no-open - 架构： - 生态定位对比： - 可观测： +- 云端部署： - 样例仓库： ## 相关项目 diff --git a/README.zh-CN.md b/README.zh-CN.md index c212f115..cccc1a9a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -53,7 +53,7 @@ agentengine web . --no-open ## 架构 -

KsADK Agent Runtime Platform 架构

+

KsADK 智能体运行时平台架构

## 文档与样例 @@ -63,6 +63,7 @@ agentengine web . --no-open - 架构： - 生态定位对比： - 可观测： +- 云端部署： - 样例仓库： ## 相关项目 diff --git a/docs-site/components/search.tsx b/docs-site/components/search.tsx index e5b23b9f..d2e53fc7 100644 --- a/docs-site/components/search.tsx +++ b/docs-site/components/search.tsx @@ -14,6 +14,7 @@ import { useDocsSearch } from 'fumadocs-core/search/client'; import { create } from '@orama/orama'; import { createTokenizer } from '@orama/tokenizers/mandarin'; import { useI18n } from 'fumadocs-ui/contexts/i18n'; +import { assetPath } from '@/lib/shared'; function initOrama(locale?: string) { if (locale === 'cn') { @@ -35,6 +36,8 @@ export default function DefaultSearchDialog(props: SharedProps) { type: 'static', initOrama, locale, + // GitHub Pages project sites live below /, not the domain root. + from: assetPath('/api/search'), }); return ( diff --git a/docs-site/content/docs/framework/getting-started/architecture.en.mdx b/docs-site/content/docs/framework/getting-started/architecture.en.mdx index 6f21e70c..836ee6ee 100644 --- a/docs-site/content/docs/framework/getting-started/architecture.en.mdx +++ b/docs-site/content/docs/framework/getting-started/architecture.en.mdx @@ -4,7 +4,7 @@ title: Architecture KsADK's public architecture is an **Agent Runtime Platform** layer. You keep building business agents with your chosen framework, while KsADK unifies runtime, debugging, protocols, tools, sandboxing, deployment, and observability. -![KsADK Agent Runtime Platform architecture](/assets/ksadk-runtime-architecture.svg) +![KsADK Agent Runtime Platform architecture](/assets/ksadk-runtime-architecture.en.svg) ## Overview diff --git a/docs-site/content/docs/framework/getting-started/quickstart.en.mdx b/docs-site/content/docs/framework/getting-started/quickstart.en.mdx index 9c34c132..5a17dd16 100644 --- a/docs-site/content/docs/framework/getting-started/quickstart.en.mdx +++ b/docs-site/content/docs/framework/getting-started/quickstart.en.mdx @@ -221,5 +221,6 @@ You now have: - Wrap an existing project in [Bring An Existing Agent](../tutorials/existing-agent). - Configure more settings in [Configuration](./configuration). - Learn framework conventions in [Frameworks](../guides/frameworks). +- Publish a validated project in [Deploy to Kingsoft Cloud](../guides/cloud-deployment). - Debug with the [Local Web UI](../guides/local-web-ui). - Check commands in the [CLI Reference](../reference/cli). diff --git a/docs-site/content/docs/framework/getting-started/quickstart.mdx b/docs-site/content/docs/framework/getting-started/quickstart.mdx index 4e2fcb6b..b0f6cb08 100644 --- a/docs-site/content/docs/framework/getting-started/quickstart.mdx +++ b/docs-site/content/docs/framework/getting-started/quickstart.mdx @@ -204,5 +204,6 @@ rm -rf .agentengine/ - 阅读 [配置项](./configuration)，理解 `.env`、YAML 和 CLI 覆盖顺序。 - 阅读 [运行时架构](../guides/runtime-architecture)，理解请求如何进入 Runner。 +- 阅读 [部署到金山云](../guides/cloud-deployment)，把已验证的项目发布为托管 Agent。 - 阅读 [OpenAI 兼容 API](../reference/openai-compatible-api)，把本地 Agent 接到客户端。 - 阅读 [本地 Web UI](../guides/local-web-ui)，了解会话、上传和工作区预览。 diff --git a/docs-site/content/docs/framework/guides/cloud-deployment.en.mdx b/docs-site/content/docs/framework/guides/cloud-deployment.en.mdx new file mode 100644 index 00000000..e3e31bc5 --- /dev/null +++ b/docs-site/content/docs/framework/guides/cloud-deployment.en.mdx @@ -0,0 +1,216 @@ +--- +title: Cloud Deployment to Kingsoft Cloud +description: Deploy a validated KsADK project as a hosted Agent, from credentials to verification. +--- + +This guide starts after a KsADK project works locally with `agentengine run . -i` +or `agentengine web .`. It explains how to deploy that project as a hosted +Agent on Kingsoft Cloud. + + + Use `launch` for a first deployment: it builds, uploads or pushes the + artifact, then creates or updates the Agent. Use `build` plus `deploy` when + your CI pipeline needs to review the artifact separately. + + +## Choose A Target + +| Target | Use it when | Default artifact | +| --- | --- | --- | +| `serverless` | You want the fastest hosted deployment for a standard Agent | `Code`, built and uploaded to KS3 automatically | +| `serverless --artifact-type Container` | The code package is large or needs system dependencies / a custom image | Container; requires Docker and a registry | +| `kce --artifact-type Container` | You already operate a KCE cluster, namespace, and registry | Container | + +`serverless` and the `Code` artifact type are the defaults. Choose Container +only for a real image requirement, a package-size limit, or an intentional KCE +deployment. + +## Prerequisites + +1. Install KsADK with the extra for your framework. For LangGraph: + + ```bash title="shell" + pip install "ksadk[langgraph]" + agentengine --version + ``` + +2. Your project needs a working `agentengine.yaml`, entry point, and dependency + manifest. Test it first: + + ```bash title="shell" + agentengine run . -i + ``` + +3. Prepare Kingsoft Cloud AK/SK credentials with permission for AgentEngine, + KS3, and the selected region. Container deployment also needs a registry you + can push to and a working local Docker installation. + +4. Never commit AK/SK credentials, model keys, registry passwords, `.env`, + `prod.env`, or `.agentengine/`. Commit only placeholder values in + `.env.example`. + +## Configure Cloud Credentials And Runtime Variables + +The interactive wizard is the simplest setup. It asks for model settings, +cloud credentials, region, and optional registry information: + +```bash title="shell" +agentengine config +``` + +For automation, write cloud credentials to the current project's uncommitted +`.env`: + +```bash title="shell" +agentengine config set \ + KSYUN_ACCESS_KEY= \ + KSYUN_SECRET_KEY= \ + KSYUN_ACCOUNT_ID= \ + KSYUN_REGION=cn-beijing-6 +``` + +`KSYUN_ACCOUNT_ID` is optional when the SDK can resolve it from AK/SK. Put only +runtime variables in a separate `prod.env`; do not put cloud AK/SK credentials +in that file: + +```bash title="prod.env" +OPENAI_API_KEY= +OPENAI_BASE_URL=https://api.example.com/v1 +OPENAI_MODEL_NAME= +``` + + + `--env-file` injects variables into the hosted runtime. Cloud credentials are + for the local deployment client and must not be forwarded as runtime env. + + +## Deploy To Serverless + +Start with a dry run to inspect the target, region, artifact type, network, and +runtime environment without creating a remote Agent: + +```bash title="shell" +agentengine launch . \ + --target serverless \ + --region cn-beijing-6 \ + --env-file ./prod.env \ + --dry-run +``` + +Remove `--dry-run` after reviewing the plan: + +```bash title="shell" +agentengine launch . \ + --target serverless \ + --region cn-beijing-6 \ + --env-file ./prod.env +``` + +This creates a Code artifact, uploads it to KS3, and creates or updates the +hosted Agent. Add `--name my-agent` to choose the name and `--no-cache` to +force a new package. + +## Build And Deploy Separately + +For CI or artifact review, build first and deploy the saved artifact reference: + +```bash title="shell" +agentengine build . --mode code --push --region cn-beijing-6 +agentengine deploy . --target serverless --region cn-beijing-6 --env-file ./prod.env +``` + +Build metadata is stored below `.agentengine/`. Use `--repackage` or +`--no-cache` when the current source must be packaged again. + +## Container And KCE + +For Container mode, configure `KCR_REGISTRY`, `KCR_USERNAME`, and +`KCR_PASSWORD`. Enterprise KCR and third-party registries require both username +and password. Personal KCR may omit `KCR_USERNAME`; the SDK falls back to +`KSYUN_ACCOUNT_ID`. + +```bash title="shell" +agentengine config set \ + KCR_REGISTRY= \ + KCR_USERNAME= \ + KCR_PASSWORD= + +agentengine launch . \ + --target serverless \ + --artifact-type Container \ + --registry \ + --env-file ./prod.env +``` + +For KCE, use the same registry and a Container artifact, then choose a +namespace: + +```bash title="shell" +agentengine launch . \ + --target kce \ + --artifact-type Container \ + --registry \ + --namespace default \ + --env-file ./prod.env +``` + +## Network And Persistent Storage + +New Agents allow public access by default. For VPC-only access, provide all +three network identifiers together: + +```bash title="shell" +agentengine launch . \ + --target serverless \ + --disable-public-access \ + --enable-vpc-access \ + --vpc-id vpc-xxxx \ + --subnet-id subnet-xxxx \ + --security-group-id sg-xxxx \ + --availability-zone cn-beijing-6a \ + --env-file ./prod.env +``` + +Hermes and OpenClaw mount persistent storage by default. `adk`, `langchain`, +`langgraph`, and `deepagents` mount storage only when you explicitly provide a +mount path. For a persistent workspace or files across restarts: + +```bash title="shell" +agentengine launch . \ + --target serverless \ + --storage-size-gi 20 \ + --storage-mount-path /home/node/.agentengine \ + --env-file ./prod.env +``` + +Storage sizes range from `20` to `500` Gi. Use `--no-storage` to explicitly +disable PVC storage. + +## Verify And Access + +After deployment, inspect the hosted Agent and then open its dashboard: + +```bash title="shell" +agentengine agent list --region cn-beijing-6 +agentengine agent status --region cn-beijing-6 +agentengine dashboard open +``` + +Record the resulting Agent ID, name, and region with the deployment. When +updating an Agent, public-access settings are retained unless you explicitly +pass `--enable-public-access` or `--disable-public-access`. + +## Troubleshooting + +| Symptom | What to check | +| --- | --- | +| Missing or invalid cloud credentials | Inspect `KSYUN_ACCESS_KEY`, `KSYUN_SECRET_KEY`, and the selected region with `agentengine config show`. | +| VPC validation fails | Supply `--vpc-id`, `--subnet-id`, and `--security-group-id` together. Availability zone is optional and cannot replace them. | +| Container build fails | Confirm Docker is running, the registry is reachable, and registry credentials match the registry type. | +| Code package is too large | Remove unnecessary dependencies first; then use `--artifact-type Container` when an image is justified. | +| Hosted runtime cannot call the model | Confirm `prod.env` was passed with `--env-file` and its variable names match the model provider used by the Agent. | + + + Run `--dry-run` whenever you first deploy, change target, or change network + settings. It checks the request plan without creating or updating a cloud Agent. + diff --git a/docs-site/content/docs/framework/guides/cloud-deployment.mdx b/docs-site/content/docs/framework/guides/cloud-deployment.mdx new file mode 100644 index 00000000..0849e38a --- /dev/null +++ b/docs-site/content/docs/framework/guides/cloud-deployment.mdx @@ -0,0 +1,206 @@ +--- +title: 云端部署到金山云 +description: 从本地项目、云账号配置到托管 Agent 验证的完整部署流程。 +--- + +本指南面向已经能在本地运行的 KsADK 项目。先用 `agentengine run . -i` 或 +`agentengine web .` 验证 Agent，再部署到金山云托管运行时。 + + + `launch` 适合首次部署：它会构建制品、上传或推送制品，并创建或更新 Agent。已有制品时，使用 + `build` 加 `deploy` 可以把构建和发布拆开。 + + +## 选择部署方式 + +| 目标 | 适用场景 | 默认制品 | +| --- | --- | --- | +| `serverless` | 最快把标准 Agent 部署为托管服务 | `Code`，自动构建并上传到 KS3 | +| `serverless --artifact-type Container` | 代码包体积较大，或依赖系统库 / 自定义镜像 | Container，需 Docker 和镜像仓库 | +| `kce --artifact-type Container` | 已有 KCE 集群、命名空间和镜像仓库 | Container | + +默认目标是 `serverless`，默认制品类型是 `Code`。只有 Code 包超过平台限制、项目依赖必须在镜像中构建，或团队明确使用 KCE 时，才选择 Container。 + +## 前置条件 + +1. 安装与项目框架匹配的 KsADK extra，例如 LangGraph： + + ```bash title="shell" + pip install "ksadk[langgraph]" + agentengine --version + ``` + +2. 本地项目必须有可运行的 `agentengine.yaml`、入口文件和依赖清单。部署前先运行： + + ```bash title="shell" + agentengine run . -i + ``` + +3. 准备金山云 AK/SK，并确保该账号有 AgentEngine、KS3 和目标区域的资源权限。Container 部署还需要 + 可推送的镜像仓库权限；本机需要可用的 Docker。 + +4. 不要把 AK/SK、模型 key 或镜像仓库密码提交到 Git。`.env`、`prod.env` 和 `.agentengine/` 应加入 + `.gitignore`，仓库中只保留 `.env.example`。 + +## 配置云账号与模型 + +最简单的方式是运行交互式向导。它会分别询问模型配置、云账号信息、区域和可选的镜像仓库信息： + +```bash title="shell" +agentengine config +``` + +也可以用非交互命令写入当前项目的未提交 `.env`： + +```bash title="shell" +agentengine config set \ + KSYUN_ACCESS_KEY= \ + KSYUN_SECRET_KEY= \ + KSYUN_ACCOUNT_ID= \ + KSYUN_REGION=cn-beijing-6 +``` + +`KSYUN_ACCOUNT_ID` 可省略，SDK 会在可用时根据 AK/SK 反查。模型 provider 配置可以继续保存在 +`.env`，也可在每次部署时通过单独的运行时 env 文件传入。 + +创建 `prod.env`，只放需要注入到运行时 Pod 的变量，不要把云账号 AK/SK 放进去： + +```bash title="prod.env" +OPENAI_API_KEY= +OPENAI_BASE_URL=https://api.example.com/v1 +OPENAI_MODEL_NAME= +``` + + + `--env-file` 的内容会进入托管运行时环境。云账号凭证用于本机调用部署 API，不应作为运行时 + env 透传；模型 key 是否需要注入取决于你的 Agent 和模型 provider。 + + +## 一次性部署到 Serverless + +先 dry run，确认项目名、区域、网络、制品类型和运行时 env： + +```bash title="shell" +agentengine launch . \ + --target serverless \ + --region cn-beijing-6 \ + --env-file ./prod.env \ + --dry-run +``` + +确认计划后，删除 `--dry-run` 执行部署： + +```bash title="shell" +agentengine launch . \ + --target serverless \ + --region cn-beijing-6 \ + --env-file ./prod.env +``` + +这会构建 Code 制品、上传到 KS3，并创建或更新同名托管 Agent。需要重新打包当前源码时加 +`--no-cache`；需要显式命名时加 `--name my-agent`。 + +## 分开构建与部署 + +CI 或需要人工审核制品时，先构建，再部署已保存的制品引用： + +```bash title="shell" +agentengine build . --mode code --push --region cn-beijing-6 +agentengine deploy . --target serverless --region cn-beijing-6 --env-file ./prod.env +``` + +`build` 会在项目 `.agentengine/` 中保存可复用的构建元数据。要忽略已有 Code 包并重新打包，使用 +`--repackage` 或 `--no-cache`。 + +## Container 与 KCE + +Container 模式适用于需要 Docker 镜像的项目。先准备 `KCR_REGISTRY`、`KCR_USERNAME` 和 +`KCR_PASSWORD`；企业版 KCR 和第三方仓库必须同时设置用户名和密码。个人版 KCR 可以省略 +`KCR_USERNAME`，SDK 会使用 `KSYUN_ACCOUNT_ID` 作为用户名兜底。 + +```bash title="shell" +agentengine config set \ + KCR_REGISTRY= \ + KCR_USERNAME= \ + KCR_PASSWORD= + +agentengine launch . \ + --target serverless \ + --artifact-type Container \ + --registry \ + --env-file ./prod.env +``` + +部署到 KCE 时使用相同的镜像仓库和 Container 制品，并按需指定命名空间： + +```bash title="shell" +agentengine launch . \ + --target kce \ + --artifact-type Container \ + --registry \ + --namespace default \ + --env-file ./prod.env +``` + +## 网络和持久化存储 + +新建 Agent 默认开启公网访问。要仅通过 VPC 访问，必须一次性提供 VPC、子网和安全组： + +```bash title="shell" +agentengine launch . \ + --target serverless \ + --disable-public-access \ + --enable-vpc-access \ + --vpc-id vpc-xxxx \ + --subnet-id subnet-xxxx \ + --security-group-id sg-xxxx \ + --availability-zone cn-beijing-6a \ + --env-file ./prod.env +``` + +Hermes 与 OpenClaw 默认挂载持久化目录。`adk`、`langchain`、`langgraph` 和 `deepagents` +只有显式指定挂载路径时才会挂盘；需要跨重启保留工作区或文件时可以这样配置： + +```bash title="shell" +agentengine launch . \ + --target serverless \ + --storage-size-gi 20 \ + --storage-mount-path /home/node/.agentengine \ + --env-file ./prod.env +``` + +存储容量范围为 `20` 到 `500` Gi。明确不需要 PVC 时使用 `--no-storage`。 + +## 验证与访问 + +部署完成后，先查看 Agent 列表和状态： + +```bash title="shell" +agentengine agent list --region cn-beijing-6 +agentengine agent status --region cn-beijing-6 +``` + +然后打开托管 Dashboard： + +```bash title="shell" +agentengine dashboard open +``` + +部署命令输出的 Agent ID、名称和区域应记录在发布记录中。更新已有 Agent 时，未显式传入的公网访问 +设置会保留远端现有值；需要改变它时显式传入 `--enable-public-access` 或 +`--disable-public-access`。 + +## 常见问题 + +| 现象 | 处理方式 | +| --- | --- | +| 缺少或无效云凭证 | 检查当前项目 `.env` 或 shell 中的 `KSYUN_ACCESS_KEY`、`KSYUN_SECRET_KEY` 和区域；先执行 `agentengine config show`。 | +| VPC 参数校验失败 | 同时传入 `--vpc-id`、`--subnet-id`、`--security-group-id`；可用区可选，不能替代这三个 ID。 | +| Container 构建失败 | 确认 Docker 可运行，`--registry` 可访问，并按仓库类型配置 KCR 凭证。 | +| Code 包过大 | 先移除不必要依赖；仍无法满足时改用 `--artifact-type Container`。 | +| 托管运行时找不到模型配置 | 检查 `prod.env` 是否通过 `--env-file` 传入，并确认其中的变量名符合 Agent 使用的模型 provider。 | + + + 每次首次部署、切换目标或修改网络设置时都先执行 `--dry-run`。它用于检查请求计划，不会创建或更新 + 云端 Agent。 + diff --git a/docs-site/content/docs/framework/meta.json b/docs-site/content/docs/framework/meta.json index 50ea054e..497487c4 100644 --- a/docs-site/content/docs/framework/meta.json +++ b/docs-site/content/docs/framework/meta.json @@ -25,6 +25,8 @@ "guides/build-and-package", "guides/frameworks", "guides/web-ui-source", + "---[Cloud]云端部署---", + "guides/cloud-deployment", "---[BookOpen]教程---", "tutorials" ] diff --git a/docs-site/content/docs/references/project-config.en.mdx b/docs-site/content/docs/references/project-config.en.mdx index 2b0c1553..e0eea2d7 100644 --- a/docs-site/content/docs/references/project-config.en.mdx +++ b/docs-site/content/docs/references/project-config.en.mdx @@ -63,6 +63,27 @@ KSADK_STM_PATH=.agentengine/ui/sessions.sqlite Only commit `.env.example` files with placeholders. Do not commit `.env`. +## Cloud Deployment Configuration + +`agentengine.yaml` can keep non-secret network defaults. Explicit CLI arguments +override file values: + +```yaml title="agentengine.yaml" +network: + enable_public_access: false + enable_vpc_access: true + vpc_id: vpc-xxxx + subnet_id: subnet-xxxx + security_group_id: sg-xxxx + availability_zone: cn-beijing-6a +``` + +VPC access requires all of `vpc_id`, `subnet_id`, and `security_group_id`. +Keep model keys, cloud AK/SK credentials, and registry passwords in an +uncommitted `.env` or local global configuration, not in YAML. See +[Deploy to Kingsoft Cloud](../framework/guides/cloud-deployment) for the +complete prerequisites, commands, and verification steps. + ## Detection Fallback If no config file exists, KsADK tries to infer project shape from: diff --git a/docs-site/content/docs/references/project-config.mdx b/docs-site/content/docs/references/project-config.mdx index ca9905de..6aceb389 100644 --- a/docs-site/content/docs/references/project-config.mdx +++ b/docs-site/content/docs/references/project-config.mdx @@ -57,6 +57,24 @@ OPENAI_MODEL_NAME=my-model 不要把真实 key、私有 endpoint、kubeconfig 或客户数据提交到 Git。 +## 云端部署配置 + +`agentengine.yaml` 可以保留不含密钥的网络默认值；命令行传参会覆盖文件中的值： + +```yaml title="agentengine.yaml" +network: + enable_public_access: false + enable_vpc_access: true + vpc_id: vpc-xxxx + subnet_id: subnet-xxxx + security_group_id: sg-xxxx + availability_zone: cn-beijing-6a +``` + +开启 VPC 时必须同时提供 `vpc_id`、`subnet_id` 和 `security_group_id`。模型 key、云账号 +AK/SK、镜像仓库密码不要写入 YAML；它们应保存在未提交的 `.env` 或本机全局配置中。完整的 +前置条件、命令和验证步骤见[部署到金山云](../framework/guides/cloud-deployment)。 + ## 检测规则 运行时优先读取显式 YAML；没有配置时才尝试 `langgraph.json`、`agent.py`、 diff --git a/docs-site/public/assets/ksadk-runtime-architecture.en.png b/docs-site/public/assets/ksadk-runtime-architecture.en.png new file mode 100644 index 00000000..121449a0 Binary files /dev/null and b/docs-site/public/assets/ksadk-runtime-architecture.en.png differ diff --git a/docs-site/public/assets/ksadk-runtime-architecture.en.svg b/docs-site/public/assets/ksadk-runtime-architecture.en.svg new file mode 100644 index 00000000..caeac82f --- /dev/null +++ b/docs-site/public/assets/ksadk-runtime-architecture.en.svg @@ -0,0 +1,204 @@ + + KsADK Agent Runtime Platform Architecture + Agent frameworks flow through the KsADK unified runtime, runtime capabilities, and local or AgentEngine hosted deployment targets. + + + + + + + + + + + + + + + + + + + + + + + KSADK / RUNTIME DATA PLANE + KsADK Agent Runtime Platform + LOCAL-FIRST / CLOUD-READY + One agent codebase from local development to hosted runtime + + + + + 01 AGENT CODE + Bring your framework + Keep your business logic + + + + + Google ADK + root_agent + + + + + LangGraph + StateGraph + + + + + LangChain + Runnable / chain + + + + + DeepAgents + create_deep_agent + + + + + + RUNNER ADAPTERS + + + + + 02 KSADK RUNTIME + One execution model · one protocol surface · one runtime contract + + + + ENTRYPOINTS + SDK + CLI + + Browser UI + OpenAI API + A2A + invoke · stream · serve + + + + + + Framework Runners + Adapt invoke · stream · tool binding + BaseRunner + + + + Conversation Runtime + invocation · streaming · session events + THE DATA-PLANE CORE + + + + Protocol Surface + OpenAI-compatible · A2A · streaming + + + + RUNTIME CAPABILITIES + + + + + + Session Continuity + state · transcript · resilient store + + + + + Checkpoint Control + resume · cancel · run events + + + + + Toolsets + MCP + discovery · policy · dispatch + + + + + Skill Runtime + discover · load · isolated execute + + + + + + Workspace + Artifacts + read · edit · lint · export + + + + + Sandbox + Approval + isolated code · tool safety + + + + + Memory + Knowledge + long-term context · retrieval + + + + + Observability + traces · usage · evaluation + + + + + + + ONE RUNTIME CONTRACT + + + 03 RUN ANYWHERE + Local to hosted, one contract + + + + + Local Runtime + CLI · Browser UI · local process + FAST FEEDBACK / NO CLOUD REQUIRED + + + + + + AgentEngine Hosted Control Plane + artifact · runtime · route · invoke · observe + + + Serverless + + Hermes + + OpenClaw + + HOSTED LIFECYCLE + PLATFORM SERVICES + + diff --git a/docs-site/public/assets/ksadk-runtime-architecture.png b/docs-site/public/assets/ksadk-runtime-architecture.png index 8182a30d..0489a23e 100644 Binary files a/docs-site/public/assets/ksadk-runtime-architecture.png and b/docs-site/public/assets/ksadk-runtime-architecture.png differ diff --git a/docs-site/public/assets/ksadk-runtime-architecture.svg b/docs-site/public/assets/ksadk-runtime-architecture.svg index 77bbadf8..cad65076 100644 --- a/docs-site/public/assets/ksadk-runtime-architecture.svg +++ b/docs-site/public/assets/ksadk-runtime-architecture.svg @@ -1,230 +1,204 @@ - - KsADK Agent Runtime Platform 架构 - 三层架构:业务 Agent 框架、KsADK Runtime 数据面、托管控制面。 + + KsADK 智能体运行时平台架构 + Agent 框架接入 KsADK 统一运行时，通过运行时能力部署到本地或 AgentEngine 托管环境。 - - - - + + + + + + + + + + + + - - - - KsADK — Agent Runtime Platform - 用户写 agent 做什么 · 平台管怎么跑 - - - - - 业务 Agent 框架（用户自带） - - - Google ADK - agent.py · root_agent - - - LangGraph - StateGraph - - - LangChain - Runnable · chain - - - DeepAgents - create_deep_agent - - - - - - - - - - - KsADK Runtime · 数据面 - runner · session/transcript · toolsets · sandbox · API - - - - - agentengine CLI - init · run · web · build · launch - - 本地 Web UI - 会话 · 附件 · workspace - - - - Runner 编排 - BaseRunner · 框架适配 - - ADKRunner - LangGraphRunner - LangChain · DeepAgents - invoke · stream · request_cancel - - - - Conversations Runtime - 对话运行时 · 数据面核心 - - session / transcript - PlatformInvocationContext - invocation_id · account_id - checkpoint / resume · SubscribeRunEvents - - - - OpenAI 兼容 API - /v1/responses · /v1/chat/completions - - 记忆与知识库 - LTM · KB · LanceDB - - - - - - - - - - - - - - - - 内置 Toolsets - - - Skill 工具 - list · load · search · execute - Skill Space · SkillService - - - Workspace 工具 - read · write · list · edit - search · lint - - - Sandbox 工具 - run_command · run_code - E2B backend - - - Web 工具 - web_fetch · web_search - SSRF 校验 - - - Platform 工具 - component_status - memory · knowledge - - - - Tool Gateway - 审批 envelope - approval_required - - - - 工具注入 - - - - - Sandbox Runtime - 通用隔离执行底座 · E2B-compatible backend - Skill Runtime + sandbox direct tools 共用 · KSADK_SANDBOX_TEMPLATE_ID - - - Skill Runtime - 发现 · 下载 · sha256 校验 · 安全解压 · loader - local_process / e2b backend · execute_skills - - - Tool Dispatcher · 渐进式披露 - list · describe · call - KSADK_BUILTIN_TOOLS_MODE: off/dispatcher/focused/deferred - - - - - - - - - - 托管层 · 控制面 - agentengine-server · 部署后端 · 平台服务 - - - AgentEngine Server - artifact · runtime lifecycle - route · auth · observe · policy + + + + + + + KSADK / RUNTIME DATA PLANE + KsADK 智能体运行时平台 + LOCAL-FIRST / CLOUD-READY + 一套 Agent 代码，贯通本地开发与云端托管 + + + + + 01 AGENT CODE + 接入你的 Agent 框架 + 业务逻辑保持原生 + + + + + Google ADK + root_agent + + + + + LangGraph + StateGraph + + + + + LangChain + Runnable / chain + + + + + DeepAgents + create_deep_agent + - - 部署后端 - Serverless · Hermes · OpenClaw + + + + 运行时适配 + + + + + 02 KSADK 运行时 + 统一执行语义 · 统一协议 · 统一运行时能力 + + + + 运行入口 + SDK + CLI + + 浏览器 UI + OpenAI API + A2A + 调用 · 流式 · 服务 + + + + + + 框架 Runner + invoke · stream · 工具绑定 + BaseRunner + + + + 对话运行时 + 调用 · 流式 · 会话事件 + 数据面核心 + + + + 协议入口 + OpenAI 兼容 · A2A · 流式 + - - Skill Service - Skill Space / Version 治理 - manifest · download url + + 运行时能力 + - - Sandbox Service - template · instance · token - AIO / Code / Browser / Private + + + + 会话连续性 + 状态 · transcript · 弹性存储 + + + + + 检查点控制 + 恢复 · 取消 · 运行事件 + + + + + 工具集 + MCP + 发现 · 策略 · 调度 + + + + + Skill Runtime + 发现 · 加载 · 隔离执行 + - - 金山云基础设施 - KS3 · KCR · KOP - 对象存储 · 镜像仓库 · 签名 + + + + Workspace + 产物 + 读取 · 编辑 · 检查 · 导出 + + + + + Sandbox + 审批 + 隔离代码 · 工具安全 + + + + + 记忆 + 知识库 + 长期上下文 · 检索 + + + + + 可观测性 + traces · 用量 · 评估 + - - - - - + + + + + 统一运行时契约 + + + 03 随处运行 + 开发与部署共享同一运行时边界 + + + + + 本地运行时 + CLI · 浏览器 UI · local process + 快速反馈 / 无需云端 + - - - 图例 - - 业务 Agent 框架 - - KsADK Runtime (Runner/API/运行时) - - 工具 / 控制面 - - 存储 / Sandbox - - 审批 / 安全 - 边界:业务 Agent 写「做什么」;KsADK 管「怎么跑」(runner·session·toolsets·sandbox·API·部署·观测) + + + + AgentEngine 托管控制面 + 产物 · 运行时 · 路由 · 调用 · 观测 + + + Serverless + + Hermes + + OpenClaw + + 托管生命周期 + 平台服务 diff --git a/docs/maintainer-approval-record.md b/docs/maintainer-approval-record.md index 4885646c..eb422b4a 100644 --- a/docs/maintainer-approval-record.md +++ b/docs/maintainer-approval-record.md @@ -30,8 +30,8 @@ Record exactly one approved source publication strategy. The approved strategy must name the reviewed commit, tag, pull request, or export archive used for: -- `ksadk-python`: clean export candidate from reviewed internal commit `e8669aa4f1c765ee5059f0e91081958f2dade00a`; local candidate directory `/tmp/ksadk-python-export-candidate-0.7.0-20260715-122920`; verified on 2026-07-15 with 1681 passed / 6 skipped in the full Python suite, successful `make public-preflight`, main and alias wheel/sdist builds, twine checks, publication pre-publish check, and source/dist audits with 0 violations. Staging E2E evidence is still required before approval. -- `ksadk-web`: npm package `@kingsoftcloud/ksadk-web@0.2.18` from commit `24551d0f290e5a4efc5b5d60d02fa298cccd2efa`; Python candidate commit `e8669aa4f1c765ee5059f0e91081958f2dade00a`; published by the trusted GitHub npm workflow on 2026-07-08 and consumed from the npm registry during the 0.7.0 candidate verification. +- `ksadk-python`: clean export candidate from reviewed internal commit `a40948ea79aed139caf2db17af38bf0032f6a73e`; local candidate directory `/tmp/ksadk-python-export-candidate-0.7.0-a40948e`; verified on 2026-07-15 with 1686 passed / 6 skipped in the full Python suite, successful clean-export `make public-preflight` (version, secret/source audit, 19 public tests, docs build, wheel/sdist, twine and artifact audit), and source/dist audits with 0 violations. Staging E2E evidence is still required before final release. +- `ksadk-web`: npm package `@kingsoftcloud/ksadk-web@0.2.19` from commit `76029d965ccc328a916bc81e8ba66b5e002a6e5b`; Python candidate commit `a40948ea79aed139caf2db17af38bf0032f6a73e`; published by the trusted GitHub npm workflow on 2026-07-15 and consumed from the npm registry during the 0.7.0 candidate verification. Both approved source references must include the current commit SHA at approval time. This prevents a stale approval record from passing after candidate diff --git a/export-manifest.json b/export-manifest.json index 42df3719..1602737d 100644 --- a/export-manifest.json +++ b/export-manifest.json @@ -1,10 +1,11 @@ { - "generatedAt": "2026-07-15T05:19:58.288176+00:00", + "generatedAt": "2026-07-15T10:49:30.407984+00:00", "targetRepository": "https://github.com/kingsoftcloud/ksadk-python", "documentation": "https://kingsoftcloud.github.io/ksadk-python/", - "exportPathCount": 552, - "excludedPathCount": 207, + "exportPathCount": 556, + "excludedPathCount": 208, "excludedPaths": [ + "docs/A2UI-agent驱动UI技术方案.md", "docs/Agent 开发者上下文接入指南.md", "docs/DeepAgents说明.md", "docs/adk-resume-integration-design.md", diff --git a/ksadk/runners/langchain_runner.py b/ksadk/runners/langchain_runner.py index 2740716a..7d8f7e06 100644 --- a/ksadk/runners/langchain_runner.py +++ b/ksadk/runners/langchain_runner.py @@ -619,13 +619,40 @@ def _extract_output(result: Any) -> str: @classmethod def _extract_recognized_output(cls, result: Any) -> str: - if isinstance(result, dict) and not any( - key in result for key in ("output", "text", "messages") - ): - return "" if result is None: return "" - return cls._extract_output(result) + if isinstance(result, str): + return result + + if isinstance(result, dict): + for key in ("output", "text"): + if key not in result: + continue + value = result[key] + if isinstance(value, str): + return value + extracted = cls._extract_recognized_output(value) + if extracted: + return extracted + if value is not None and not isinstance(value, (dict, list, tuple)): + return str(value) + + message_state = cls._extract_message_state(result) + return message_state[0] if message_state else "" + + if isinstance(result, (list, tuple)): + for item in reversed(result): + extracted = cls._extract_recognized_output(item) + if extracted: + return extracted + return "" + + command_update = getattr(result, "update", None) + if isinstance(command_update, dict): + return cls._extract_recognized_output(command_update) + + content = cls._ai_message_content(result) + return content if content is not None else "" @classmethod def _extract_message_state(cls, chunk: Any) -> tuple[str, str] | None: diff --git a/scripts/generate_public_assets.py b/scripts/generate_public_assets.py index 36042d3f..b81381dd 100644 --- a/scripts/generate_public_assets.py +++ b/scripts/generate_public_assets.py @@ -27,6 +27,12 @@ ASSETS_DIR = ROOT / "docs-site" / "public" / "assets" ARCH_SVG = ASSETS_DIR / "ksadk-runtime-architecture.svg" ARCH_PNG = ASSETS_DIR / "ksadk-runtime-architecture.png" +ARCH_EN_SVG = ASSETS_DIR / "ksadk-runtime-architecture.en.svg" +ARCH_EN_PNG = ASSETS_DIR / "ksadk-runtime-architecture.en.png" +ARCHITECTURE_ASSETS = ( + (ARCH_SVG, ARCH_PNG), + (ARCH_EN_SVG, ARCH_EN_PNG), +) HERO_PNG = ASSETS_DIR / "ksadk-runtime-platform-hero.png" DEMO_GIF = ASSETS_DIR / "ksadk-local-debugging-demo.gif" WEB_UI_SCREENSHOT = ASSETS_DIR / "ksadk-web-ui-screenshot.png" @@ -58,131 +64,36 @@ def generate_architecture_svg() -> None: + """Validate the checked-in bilingual architecture SVG sources.""" ASSETS_DIR.mkdir(parents=True, exist_ok=True) - svg = """ - KsADK Agent Runtime Platform 架构图 - 从 Agent 代码到 KsADK SDK、统一运行时、Skill Runtime、Workspace、Sandbox、Memory Knowledge、AgentEngine、Serverless、Hermes 和 OpenClaw 的运行链路。 - - - - - - - - - - - - - - - - - - - - - - - KsADK Agent Runtime Platform - 一次构建 Agent，到处运行：统一开发、调试、运行、沙箱、部署和观测体验 - - - AGENT CODE - - - Google ADK - - LangGraph - - LangChain - - DeepAgents - - - - - - - KsADK SDK - Runner 适配 / 配置管理 / Toolsets / 项目打包 - - - - - - - 统一运行时 - CLI / Browser Web UI / OpenAI-Compatible API / Streaming Sessions - 本地开发时即验证部署后的运行边界 - - - - - - - - - - - Skill Runtime - Skill Space / workflow - - - Workspace - 会话文件 / artifacts - - - Sandbox - 隔离命令 / 代码执行 - - - Memory & Knowledge - 长期记忆 / 知识库 - - - - - - - - - - AgentEngine - 远端运行、服务入口与平台能力 - - - - - - - Serverless / Hermes / OpenClaw Runtime - - -""" - ARCH_SVG.write_text(svg, encoding="utf-8") + missing = [path for path, _ in ARCHITECTURE_ASSETS if not path.exists()] + if missing: + names = ", ".join(str(path.relative_to(ROOT)) for path in missing) + raise RuntimeError(f"Missing architecture SVG assets: {names}") def render_architecture_png() -> None: - if ARCH_PNG.exists() and os.environ.get("KSADK_REGENERATE_ARCHITECTURE_PNG") != "1": - return + """Render both checked-in architecture SVGs when requested or absent.""" converter = shutil.which("rsvg-convert") if converter is None: raise RuntimeError("rsvg-convert is required to render architecture PNG") - subprocess.run( - [converter, str(ARCH_SVG), "--width", "1600", "--output", str(ARCH_PNG)], - check=True, - ) - + regenerate = os.environ.get("KSADK_REGENERATE_ARCHITECTURE_PNG") == "1" + for svg_path, png_path in ARCHITECTURE_ASSETS: + if png_path.exists() and not regenerate: + continue + subprocess.run( + [ + converter, + str(svg_path), + "--width", + "2880", + "--height", + "1800", + "--output", + str(png_path), + ], + check=True, + ) def _capture_cli_help_plain() -> str: env = os.environ.copy() @@ -588,8 +499,9 @@ def main() -> int: render_architecture_png() generate_web_ui_assets() print(f"generated {HERO_PNG.relative_to(ROOT)}") - print(f"generated {ARCH_SVG.relative_to(ROOT)}") - print(f"generated {ARCH_PNG.relative_to(ROOT)}") + for svg_path, png_path in ARCHITECTURE_ASSETS: + print(f"generated {svg_path.relative_to(ROOT)}") + print(f"generated {png_path.relative_to(ROOT)}") print(f"generated {WEB_UI_SCREENSHOT.relative_to(ROOT)}") print(f"generated {DEMO_GIF.relative_to(ROOT)}") return 0 diff --git a/tests/test_public_release_positioning.py b/tests/test_public_release_positioning.py index d4ea82d8..bca492e1 100644 --- a/tests/test_public_release_positioning.py +++ b/tests/test_public_release_positioning.py @@ -15,6 +15,7 @@ f"{DOCS_ROOT_URL}cn/docs/framework/getting-started/architecture/", f"{DOCS_ROOT_URL}cn/docs/framework/getting-started/comparison/", f"{DOCS_ROOT_URL}cn/docs/framework/guides/observability-tracing/", + f"{DOCS_ROOT_URL}cn/docs/framework/guides/cloud-deployment/", } EN_DOC_URLS = { f"{DOCS_ROOT_URL}en/docs/framework/getting-started/quickstart/", @@ -22,6 +23,7 @@ f"{DOCS_ROOT_URL}en/docs/framework/getting-started/architecture/", f"{DOCS_ROOT_URL}en/docs/framework/getting-started/comparison/", f"{DOCS_ROOT_URL}en/docs/framework/guides/observability-tracing/", + f"{DOCS_ROOT_URL}en/docs/framework/guides/cloud-deployment/", } @@ -66,7 +68,7 @@ def test_public_readme_language_variants_keep_homepage_shape(): zh_readme = _read("README.zh-CN.md") en_readme = _read("README.en.md") - for text in (root_readme, zh_readme, en_readme): + for text in (root_readme, zh_readme): assert "Kingsoft Cloud Agent Development Kit" in text assert "ksadk-runtime-platform-hero-wide.png" in text assert "ksadk-web-ui-screenshot.png" in text @@ -75,6 +77,15 @@ def test_public_readme_language_variants_keep_homepage_shape(): assert "发布版本：" not in text assert "## 0.6." not in text + assert "Kingsoft Cloud Agent Development Kit" in en_readme + assert "ksadk-runtime-platform-hero-wide.png" in en_readme + assert "ksadk-web-ui-screenshot.png" in en_readme + assert "ksadk-local-debugging-demo.gif" in en_readme + assert "ksadk-runtime-architecture.en.png" in en_readme + assert "ksadk-runtime-architecture.png" not in en_readme + assert "发布版本：" not in en_readme + assert "## 0.6." not in en_readme + assert _github_pages_urls(root_readme) == {DOCS_ROOT_URL, *ZH_DOC_URLS} assert _github_pages_urls(zh_readme) == {DOCS_ROOT_URL, *ZH_DOC_URLS} assert _github_pages_urls(en_readme) == {DOCS_ROOT_URL, *EN_DOC_URLS} @@ -115,6 +126,17 @@ def test_public_readme_docs_links_match_fumadocs_routes(): assert candidate.exists() or index_candidate.exists(), url +def test_docs_site_cloud_deployment_guides_and_static_search_are_publicly_reachable(): + docs_root = ROOT / "docs-site" + search = _read("docs-site/components/search.tsx") + + assert "from: assetPath('/api/search')" in search + assert "import { assetPath } from '@/lib/shared'" in search + assert (docs_root / "content/docs/framework/guides/cloud-deployment.mdx").exists() + assert (docs_root / "content/docs/framework/guides/cloud-deployment.en.mdx").exists() + assert '"guides/cloud-deployment"' in _read("docs-site/content/docs/framework/meta.json") + + def test_legacy_deploy_and_examples_are_not_tracked_in_source_repo(): if not (ROOT / ".git").exists(): return @@ -184,10 +206,10 @@ def test_pypi_publish_workflow_uses_trusted_publishing_and_bundles_ksadk_web(): assert "workflow_dispatch:" in workflow assert "publish_target:" in workflow assert "alias-only" in workflow - assert 'default: "0.2.18"' in workflow + assert 'default: "0.2.19"' in workflow assert "approved_source_commit:" in workflow assert "Reviewed source commit SHA recorded in docs/maintainer-approval-record.md" in workflow - assert "KSADK_WEB_VERSION: ${{ github.event.inputs.ksadk_web_version || '0.2.18' }}" in workflow + assert "KSADK_WEB_VERSION: ${{ github.event.inputs.ksadk_web_version || '0.2.19' }}" in workflow assert ( "KSADK_APPROVED_SOURCE_COMMIT: " "${{ github.event.inputs.approved_source_commit || " @@ -205,7 +227,7 @@ def test_pypi_publish_workflow_uses_trusted_publishing_and_bundles_ksadk_web(): assert "make public-test" in ci_workflow assert "tests/test_conversation_runtime.py" not in ci_workflow assert "tests/test_server_session_app.py" not in ci_workflow - assert 'KSADK_WEB_VERSION: "0.2.18"' in ci_workflow + assert 'KSADK_WEB_VERSION: "0.2.19"' in ci_workflow assert "PUBLIC_KSADK_WEB_VERSION" not in ci_workflow assert "KSADK_WEB_VERSION ?= latest" in makefile assert (