全部文档
当前文档
最近更新时间：2026-07-28 10:35:26
本文演示如何从 KSADK 官方样例仓库获取一个 LangGraph 知识库问答智能体，在本地完成最小验证，并使用 AgentEngine CLI 一次性完成代码打包、上传 KS3 和创建 AgentEngine 运行时。
完成本文后，您将得到一个处于“运行中”状态、可通过控制台或 CLI 在线调用的知识库问答智能体。
本文只介绍从官方样例到云端运行的最短路径。知识库、记忆库、MCP、沙箱、评测和生产治理等能力，请参见《进阶入门：智能体开发》。
本次实践使用 KSADK 官方 knowledge-base-rag/langgraph 样例：
AgentEngine CLI 版本：0.7.0
部署方式：Serverless Code
构建产物：knowledge_base_rag_langgraph.zip
代码包大小：50.62 MB
KS3 上传耗时：36.0 秒
运行时状态：RUNNING
副本状态：1/1 就绪
在线调用：成功返回知识库问答结果
快速部署包含以下五个步骤：
获取 KSADK 官方知识库问答样例。
配置模型和金山云身份凭证。
在本地启动并调用 Agent。
使用 AgentEngine CLI 构建代码包、上传 KS3 并部署运行时。
在控制台或 CLI 中验证云端 Agent。
其中，第 4 步只需要执行一条命令。构建产物必须由 AgentEngine CLI 生成，请勿手工压缩项目目录后上传。
开始前，请确认已具备以下条件：
已开通星源 AgentKit 和 AgentEngine 服务。
本机已安装 Git 和 Python 3.12 或更高版本。
已取得一个 OpenAI 兼容模型服务的 API Key、Base URL 和模型名称。
已创建金山云 IAM AccessKey，并保存 AccessKey ID 和 Secret AccessKey。
当前 IAM 用户具备创建 AgentEngine 运行时和向 KS3 上传代码包所需的权限。
创建并激活 Python 3.12 虚拟环境，然后安装 KSADK。
python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# macOS 或 Linux
source .venv/bin/activate
python -m pip install -U "ksadk[all]"
agentengine --version当终端可以输出 AgentEngine CLI 版本号时，说明安装成功。
克隆 KSADK 官方样例仓库，并进入 LangGraph 知识库问答样例目录。
git clone https://github.com/kingsoftcloud/ksadk-samples.git
cd ksadk-samples/02-use-cases/knowledge-base-rag/langgraph
python -m pip install -r requirements.txt样例中最重要的三个文件如下：
langgraph/
├── agent.py # LangGraph 智能体入口，暴露 root_agent
├── agentengine.yaml # AgentEngine 项目描述
└── requirements.txt # Python 依赖agentengine.yaml 描述了框架、入口文件和 Agent 变量：
name: knowledge-base-rag-langgraph
framework: langgraph
entry_point: agent.py
agent_variable: root_agentAgentEngine 运行时会根据该文件加载 agent.py 中的 root_agent。
在 Agent 项目目录执行：
agentengine config根据提示配置 Agent 名称、LangGraph 框架、模型 API Key、Base URL、模型名称、金山云 AK/SK 和默认区域。
也可以在项目的 .env 中检查配置。以下仅为变量名示例：
OPENAI_API_KEY=<MODEL_API_KEY>
OPENAI_BASE_URL=<OPENAI_COMPATIBLE_BASE_URL>
OPENAI_MODEL_NAME=<MODEL_NAME>
KSYUN_ACCESS_KEY=<IAM_ACCESS_KEY_ID>
KSYUN_SECRET_KEY=<IAM_SECRET_ACCESS_KEY>
KSYUN_REGION=cn-beijing-6先检查 Python 文件能否导入，再启动本地服务。
python -m py_compile agent.py common/kb_runtime.py common/local_kb.py common/model_config.py
agentengine run -i .AgentEngine CLI 会读取 agentengine.yaml，加载 root_agent 并启动本地 HTTP 服务。
在另一个终端执行一次调用：
agentengine agent invoke --local --message "KSADK 如何部署 Agent？"当 Agent 返回回答时，说明以下链路已经打通：
LangGraph 入口可以加载。
模型 API Key、Base URL 和模型名称有效。
本地知识库可以读取。
AgentEngine 运行协议正常。
AgentEngine CLI 提供 launch 命令，一次完成以下动作：
检查项目配置和依赖。
生成 AgentEngine 运行入口。
安装或复用 Linux 依赖缓存。
使用 CLI 生成 Code ZIP。
将 ZIP 上传至 KS3。
创建或更新 AgentEngine Serverless 运行时。
首次部署建议先执行一次预检查：
agentengine launch . \
--target serverless \
--artifact-type Code \
--name ksadk-kb-rag-quickstart \
--region cn-beijing-6 \
--enable-public-access \
--env-file runtime.env \
--dry-run确认区域、Agent 名称、框架和环境变量无误后，去掉 --dry-run：
agentengine launch . \
--target serverless \
--artifact-type Code \
--name ksadk-kb-rag-quickstart \
--region cn-beijing-6 \
--enable-public-access \
--env-file runtime.envWindows PowerShell 可以将命令写在一行：
agentengine launch . --target serverless --artifact-type Code --name ksadk-kb-rag-quickstart --region cn-beijing-6 --enable-public-access --env-file runtime.env命令返回“部署成功”表示控制面已经接受创建或更新请求。运行时启动是异步过程，仍需等待状态变为“运行中”，不能只以 CLI 请求成功作为最终验收条件。
登录星源 AgentKit 控制台，在左侧导航栏选择 Agent Engine > 运行时。
在运行时列表中找到 ksadk-kb-rag-quickstart。当状态显示“运行中”时，表示运行时已经完成启动并可以接收请求。
也可以通过 CLI 查询：
agentengine agent status --agent <AGENT_ID> --region cn-beijing-6本次实践的最终状态为：
status: RUNNING
phase: Running
replicas: 1
ready_replicas: 1在控制台运行时列表中单击 在线调试，输入：
KSADK 如何部署 Agent？也可以使用 AgentEngine CLI：
agentengine agent invoke \
--agent <AGENT_ID> \
--region cn-beijing-6 \
--message "KSADK 如何部署 Agent？"本次云端调用成功检索了随代码包上传的 KSADK 部署知识，并返回了 agentengine deploy .、本地验证和部署后调用等步骤。
至此，官方样例已经完成从 GitHub 代码、本地验证、CLI 构建、KS3 上传到 AgentEngine 运行和在线调用的完整闭环。
快速部署验证的是“KSADK 项目能否稳定进入 AgentEngine 并提供服务”。当团队需要将真实业务 Agent 上线时，还需要继续处理：
知识库、记忆库、MCP、沙箱和 Skills 的控制台配置与代码接入。
开发、测试、预发布和生产环境隔离。
IAM 最小权限、密钥轮换和敏感变量治理。
Trace、日志、指标和评测集。
相关实践请继续阅读《进阶入门：智能体开发》。
纯净模式