ksadk 0.3.0

Kingsoft Cloud Agent Development Kit - 支持 LangChain/LangGraph/DeepAgents/ADK 的本地运行与云端部署

ksadk (AgentEngine CLI)

ksadk 是金山云 Agent 开发与部署工具链，提供统一的 CLI 体验，覆盖本地开发、构建、部署、调用、版本管理与 MCP Server 管理。

当前版本：0.3.0

核心能力

• 多框架支持：DeepAgents、LangGraph、LangChain、Google ADK。
• ADK 增强能力：支持短期/长期记忆体（STM/LTM）与知识库工具注入。
• 本地开发：run（API/TUI）与 web（本地 Invoke 调试 UI）。
• 云端部署：build、deploy、launch，支持 Code / Container 两种制品模式。
• 云端 UI 访问：dashboard 统一打开已部署 Agent 的 Web UI（含 OpenClaw）。
• 统一控制面：通过 AgentEngine Server 进行 Agent/MCP 管理。
• 状态持久化：部署后保存 .agentengine.state，供后续 status/invoke/destroy/version 复用。
• 版本管理：version list/release/rollback。
• MCP 管理：mcp deploy/list/status/delete。

安装

pip install -U ksadk

可选依赖：

pip install "ksadk[langgraph]"
pip install "ksadk[langchain]"
pip install "ksadk[deepagents]"
pip install "ksadk[adk]"
pip install "ksadk[kb]"

安装后可使用以下命令入口（等价）：

agentengine --help
ksadk --help

快速开始

1) 初始化项目

agentengine init my_agent -f langgraph
cd my_agent

DeepAgents 模板：

agentengine init my_deep_agent -f deepagents
cd my_deep_agent

也可包装已有代码：

agentengine init --from-agent ./my_agent.py
agentengine init --from-agent ./my_agent_dir

2) 交互式配置

agentengine config

会生成或更新：

• agentengine.yaml
• .env

3) 本地调试

agentengine run -i

或启动 Web UI：

agentengine web --port 8080

4) 一键构建+部署

export KSYUN_ACCESS_KEY=your-ak
export KSYUN_SECRET_KEY=your-sk
export KSYUN_ACCOUNT_ID=your-account-id
export KSYUN_REGION=cn-beijing-6

agentengine launch . --target serverless

5) 打开云端已部署 Agent UI

# 目录内自动解析 agent（.agentengine.state -> agentengine.yaml/ksadk.yaml）
agentengine dashboard

# 显式指定 Agent
agentengine dashboard --agent ar-xxxx

# OpenClaw 也走统一入口
agentengine dashboard --agent openclaw-gateway-xxxx

6)（可选）启用 ADK 记忆与知识库

# 记忆体后端: local | http | sdk
export KSADK_LTM_BACKEND=local

# 配置知识库后，Runner 会自动注入 search_knowledge_base 工具
export KSADK_KB_DATASET_ID=your_dataset_id

命令总览

• agentengine init：创建新项目（支持 --from-agent）。
• agentengine config：交互式配置 agentengine.yaml + .env。
• agentengine model：从模型服务拉取模型列表并更新 .env 的 OPENAI_MODEL_NAME。
• agentengine run：本地运行 Agent（支持 -i TUI）。
• agentengine web：启动本地调试 UI（ADK 项目用 ADK Web，其他用 Chainlit）。
• agentengine dashboard：打开云端已部署 Agent 的 Dashboard/WebUI。
• agentengine build：构建制品（code 或 container）。
• agentengine deploy：部署到 serverless / kcf / kce。
• agentengine launch：build + deploy 一条命令完成。
• agentengine status：查看运行状态与 endpoint。
• agentengine invoke：调用远端或本地 Agent。
• agentengine destroy：销毁 Agent。
• agentengine version：版本管理（list/release/rollback）。
• agentengine mcp：MCP Server 管理。
• agentengine openclaw：一键拉起 OpenClaw（部署/状态/删除等）。
• agentengine completion：Shell 补全脚本与自动安装。

说明：

• agentengine openclaw dashboard 已收敛为统一命令 agentengine dashboard。
• dashboard 默认通过 CreateDashboardTicket 直开浏览器；CreateDashboardTicket 不可用时不会回退 API Key URL 票据。

Agent 指定规则（统一）

适用于：status、invoke、destroy、version 子命令。

支持三种写法：

• 推荐：--agent <id-or-name>
• 兼容：--agent-id <id-or-name>
• 位置参数：<id-or-name>

示例：

agentengine status --agent ar-xxxx
agentengine status ar-xxxx
agentengine invoke --agent my_agent -m "你好"
agentengine destroy my_agent
agentengine version list --agent ar-xxxx

未显式传 Agent 时，自动解析顺序为：

1. .agentengine.state（优先 agent_id，其次 name）
2. agentengine.yaml / ksadk.yaml 的 name

构建与部署

build

# 1) 默认构建 (code 模式)
agentengine build .

# 2) 显式指定构建参数
agentengine build . --mode container --push --registry hub-cn-beijing-6.kce.ksyun.com
# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine build . --mode code --push --no-cache

deploy

# 1) 默认部署 (serverless)
agentengine deploy .
# 2) 显式指定部署参数
agentengine deploy . --target kcf --account-id X-Ksc-Account-Id
# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine deploy . --target serverless --dry-run

常用参数：

• --artifact-type [Code|Container]
• --region
• --account-id
• --observability/--no-observability
• --no-version
• --auto-rollback

launch

# 1) 默认一键部署 (serverless)
agentengine launch .
# 2) 显式指定部署参数
agentengine launch . --target kce --artifact-type Container
# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine launch . --target serverless --no-cache

版本管理

# 1) 目录内自动解析 agent（优先 .agentengine.state）
agentengine version list

# 2) 显式指定 agent
agentengine version list --agent ar-xxxx
agentengine version release --agent ar-xxxx --tag v1.0.1 --description "release note"
agentengine version rollback --agent ar-xxxx --to v1.0.0 -y

# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine version list --agent ar-xxxx
KSYUN_REGION=cn-beijing-6 agentengine version release --agent ar-xxxx --tag v1.0.1
KSYUN_REGION=cn-beijing-6 agentengine version rollback --agent ar-xxxx --to v1.0.0 -y

MCP Server 管理

# 1) 默认部署
agentengine mcp deploy .
# 2) 常用查询
agentengine mcp list
# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine mcp status <mcp_id>
# 删除
agentengine mcp delete <mcp_id> --yes

关键文件

• agentengine.yaml：项目配置（name/framework/entry_point 等）。
• .env：模型、云凭证、可观测性配置。
• .agentengine.state：部署后本地状态（agent_id / endpoint / api_key / region）。
• ~/.agentengine/settings.json：全局配置（可被 config --global 更新）。

环境变量

变量名	说明
OPENAI_API_KEY	模型 API Key
OPENAI_BASE_URL	模型 API Base URL
OPENAI_MODEL_NAME	模型名称
KSYUN_ACCESS_KEY	金山云 AK
KSYUN_SECRET_KEY	金山云 SK
KSYUN_ACCOUNT_ID	金山云账号 ID
KSYUN_REGION	默认区域
LANGFUSE_PUBLIC_KEY	Langfuse 公钥
LANGFUSE_SECRET_KEY	Langfuse 私钥
LANGFUSE_BASE_URL / LANGFUSE_HOST	Langfuse 地址
KSADK_LTM_BACKEND	ADK 长期记忆后端（local/http/sdk）
KSADK_LTM_HTTP_URL	LTM HTTP 后端地址（当 KSADK_LTM_BACKEND=http）
KSADK_KB_DATASET_ID	知识库 Dataset ID（配置后启用知识库检索）

兼容别名仍可识别：OPENAI_API_BASE、MODEL_NAME。

架构说明

云端链路：

CLI (ksadk) -> AgentEngine Server (控制面) -> Serverless/KCF/KCE

本地链路：

CLI (run/web) -> Unified Runner -> 本地 Agent 进程

补全

agentengine completion install --shell auto

示例项目

见 examples 目录。

进阶文档

• DeepAgents 框架支持说明
• ADK 记忆能力使用说明
• 知识库与记忆能力示例