新版本要求 Python 3.12 或以上；已有 Agent 可保留原 SDK 和运行镜像，旧 Runtime 的会话读取与订阅协议继续兼容。
金山云智能体开发套件
构建、部署、调试、观测企业级 AI 智能体的一站式云原生框架。 兼容 Google ADK、LangGraph、LangChain 与 DeepAgents，并支持一键拉起 OpenClaw 和 Hermes 运行时。
python -m venv .venv
source .venv/bin/activate
pip install -U "ksadk[all]"
agentengine init demo-agent -f langgraph
cd demo-agent
agentengine config set OPENAI_API_KEY=your-api-key OPENAI_MODEL_NAME=gpt-4o-mini
agentengine run -i启动本地调试 Web UI：
agentengine web . --no-open0.8.7 要求 Python 3.12+，内置 Web companion 为 0.3.18。
下表介绍本版本能力；安装前核对 GitHub Release 与两个 PyPI 发行包的版本。
| 能力 | 如何接入 |
|---|---|
| AG-UI / A2UI | 安装 agui extra，在自有图中接入结构化输入、业务 Schema 与持久化 checkpoint。 |
| OAuth MCP / API Key MCP | OAuth 使用 McpOAuthTools 与本地 Web/托管 Broker；原 API Key 客户端继续使用。 |
| A2A | 绑定 Space、注册 callee，再通过发现工具调用；注册与 Gateway 属于配套平台。 |
| 会话与恢复 | 分别配置 Session 和框架 checkpoint；托管模式显式请求 Kernel 准入。 |
详见功能接入与配置、 AG-UI/A2UI 示例、 OAuth MCP 和 A2A。 模型生成的 A2UI 仍需通过注册目录校验，复杂样式可能失败；不把生成失败包装为业务成功。
KsADK 把“框架适配”收敛为稳定的运行时分层，同时保留各框架的原生执行语义：
- 可信内核：统一并发、取消、恢复、状态一致性和运行时安全边界。
- Harness 执行层：负责装配、Activation、生命周期和共用能力注入；一次 Activation 只选择一个 Provider。
- 可插拔 Provider：Codex、KsADK Harness、DSH/Cordis 与 Subagent 在同一 Harness 契约下运行，Provider 保留原生线程、checkpoint 与事件语义。
- 统一事件：
RuntimeEvent(schema_version=2)是存储、回放、API、Studio 与托管界面的事件事实来源；v1 仅作为只读兼容投影。 - 受控插件化：DSH Bundle/Profile 使用固定工具链、不可变来源摘要和失败回滚；Codex 官方插件仍由 Codex App Server 管理。
- 平台资源插件：Studio 可绑定知识库、长期记忆与 Skill Center；Agent Revision 保存资源选择，Build 固化连接引用和插件摘要，Runtime 在 Activation 时按平台授权装配。
- 消息渠道连接：Studio 内置官方 Channel UI；本地和高代码 Agent 可通过
ksadk.connector出站 WSS 接入独立 Channel 服务，不需要开放本地端口或安装agentengine-channel。 - 本地开发闭环：Studio 覆盖创建、构建、调试、评测与本地 Scheduler Lite，并复用独立发布的
@kingsoftcloud/ksadk-web会话组件。
从 运行时架构、AgentKit Local Studio、Channel Connector 和插件与自动化开始阅读。版本说明与制品校验信息见 GitHub Releases。
运行事件主路径固定为 canonical RuntimeEvent(schema_version=2)；能力描述为 RuntimeEventVersions=[1,2]、RuntimeEventDefault=2、RuntimeEventV1ProjectionModes=["snapshot_only","identity_replace"]、RuntimeEventV1ProjectionDefault="snapshot_only"。v1 仅作只读兼容投影。
大多数 Agent 框架解决“如何开发 Agent”。KsADK 解决“如何运行、调试、部署和观测 Agent”。
- 本地开发：
agentengine init、agentengine run、agentengine web。 - 统一调试：浏览器 Web UI、streaming、附件、workspace 文件、工具调用和会话。
- 统一协议：本地
/v1/responses与/v1/chat/completions。 - 工具边界：Skill Runtime、Workspace、Sandbox、Memory、Knowledge。
- 工程链路：打包、部署、OpenClaw / Hermes 运行时、OpenTelemetry 可观测。
Agent Kernel 收口可信控制，Harness 管理装配与生命周期，可插拔 Provider 保留框架原生执行语义；RuntimeEvent v2 为 API、Studio 与托管界面提供统一事件事实链。
- 文档：https://kingsoftcloud.github.io/ksadk-python/
- 快速开始：https://kingsoftcloud.github.io/ksadk-python/cn/docs/framework/getting-started/quickstart/
- 为什么需要 KsADK：https://kingsoftcloud.github.io/ksadk-python/cn/docs/framework/getting-started/why-ksadk/
- 架构：https://kingsoftcloud.github.io/ksadk-python/cn/docs/framework/getting-started/architecture/
- 生态定位对比：https://kingsoftcloud.github.io/ksadk-python/cn/docs/framework/getting-started/comparison/
- 可观测：https://kingsoftcloud.github.io/ksadk-python/cn/docs/framework/guides/observability-tracing/
- 云端部署：https://kingsoftcloud.github.io/ksadk-python/cn/docs/framework/guides/cloud-deployment/
- Hosted UI 与事件回放：https://kingsoftcloud.github.io/ksadk-python/cn/docs/framework/guides/hosted-ui-events/
- 环境变量：https://kingsoftcloud.github.io/ksadk-python/cn/docs/references/environment-variables/
- 样例仓库：https://github.com/kingsoftcloud/ksadk-samples
- KsADK 仓库：https://github.com/kingsoftcloud/ksadk-python
- Web UI 仓库：https://github.com/kingsoftcloud/ksadk-web
- PyPI：https://pypi.org/project/ksadk/
欢迎通过 issue、PR、样例和文档改进参与贡献。提交前建议运行：
make public-preflight开源协议：Apache-2.0。