全部文档
当前文档

热搜词推荐

云服务器 虚拟私有网络 边缘节点计算 对等连接

共搜索到 0 条结果

暂无内容

如果没有找到您期望的内容，请尝试其他搜索词

文档中心

金山云星源AgentKit

查看更多结果
未找到含当前关键字的文档标题
页面目录
全部展开全部收起
未找到含该关键词的产品
文档中心 金山云星源AgentKit 快速入门 进阶入门:智能体开发

进阶入门:智能体开发

最近更新时间：2026-07-28 10:35:09

本文以一个 LangGraph 企业应用为例，演示如何把知识库、长期记忆、MCP、Sandbox、Workspace、Skills、AI 搜索和可观测能力接入同一个 Agent，并通过 AgentEngine CLI 将 Code 制品自动上传 KS3、发布为 Serverless 运行时。

本文面向已经完成《快速入门》和《入门指引》的开发者。快速部署强调“从 KSADK 样例到云端运行”的最短路径；本文强调业务工程治理、多组件协作、可追踪验证和故障恢复。

实践结果

本次实践使用以下统一标识：

  • 应用名称：企业云资源运营助手

  • 工程与运行时名称：enterprise-cloud-assistant

  • 测试资源前缀：enterprise-bp-20260723

  • 区域：cn-beijing-6

  • 框架：LangGraph

  • 制品类型：Serverless Code

  • 制品传输：AgentEngine CLI 自动打包并上传 KS3

一、企业级实践与快速部署有什么不同

快速部署解决的是“能否把一个 Agent 运行起来”。企业级实践还要回答：

  1. 业务源码是否可以安全交付，且不泄漏客户名称、账号和凭证。

  2. 本地、Code 制品和云端运行时是否使用同一份依赖契约。

  3. 知识库、MCP、Sandbox 等组件是否真的被调用，而不只是显示“已配置”。

  4. 长对话、工具失败、版本更新和回滚是否可追踪。

  5. 验收证据能否对应到真实命令、真实资源和真实运行日志。

因此，本文采用“一套脱敏工程、一个 AgentEngine 运行时、多个受控平台组件、两组长会话”的设计。

二、总体架构

架构分为四层：

  • 前端表现层：React SPA 负责 SSE 流式渲染、知识切片卡片和计费面板。

  • 应用网关层：FastAPI 负责 JWT 鉴权、routes_chat、SSE 分发和 SPA 托管；AgentManager 管理会话，query_rewriter 补全短期上下文。

  • Agent 核心层：LangGraph、ChatOpenAI 和模块级 root_agent 共同完成 ReAct 循环与工具编排。

  • KSADK 平台能力层：知识库、长期记忆、MCP、Sandbox 和 Trace 为核心底座。

三、前提条件与安全边界

开始前需要：

  • Python 3.12。

  • KSADK / AgentEngine CLI 0.6.8。

  • Docker Desktop，用于本地容器验证。

  • 星源 AgentKit、AgentEngine、知识库、MCP、Sandbox 等服务权限。

  • IAM AccessKey，用于控制面调用和 KS3 上传。

  • AgentKit API Key，用于 MCP、AI 搜索等平台工具。

  • 一个 OpenAI 兼容模型服务。

凭证分层

凭证

用途

存放位置

IAM AK/SK

AgentEngine、知识库、MCP 和 KS3 控制面调用

本地 .env 或控制台密文变量

AgentKit API Key

MCP、AI 搜索、Sandbox 等平台能力

控制台密文变量

模型 API Key

OpenAI 兼容模型调用

控制台密文变量

AgentEngine API Key

访问已部署运行时

.agentengine.state 或安全密钥系统

四、接入平台能力

4.1 AgentEngine Toolsets

使用 KSADK 公共接口加载紧凑工具集：

from ksadk.toolsets import get_agentengine_tools

platform_tools = list(
    get_agentengine_tools(include=["focused", "tool_dispatcher"])
)

合并业务工具和平台工具时必须按工具名去重，避免模型面对重名工具时产生不稳定选择。

4.2 企业知识库

本次创建 enterprise-bp-20260723-kb，导入三份不含真实业务数据的测试文档：

企业云资源产品与区域说明.md
企业云资源计费规则.md
企业运维响应规范.md

代码侧只引用数据集 ID：

KSADK_KB_DATASET_ID=<DATASET_ID>
KSADK_KB_ENDPOINT=<AICP_ENDPOINT>
KSADK_KB_SCHEME=http

4.3 长期记忆

长期记忆用于保存角色、区域和工作偏好，不应保存密钥或完整业务数据。

KSADK_LTM_BACKEND=sdk
KSADK_LTM_NAMESPACE=<MEMORY_NAMESPACE>
KSADK_LTM_ENDPOINT=<AICP_ENDPOINT>
KSADK_LTM_SCHEME=http

4.4 MCP

本次注册了一个中性的企业指标 MCP：

  • 协议：Streamable HTTP

  • 状态：Active

  • 工具：指标汇总、指标明细

MCP 后端地址和认证值由平台保存，文档、运行日志和 Agent 回复都不展示真实值。Agent 只通过 MCP Server ID 和 AgentKit API Key 使用平台能力。

4.5 Sandbox

Sandbox 用于执行确定性计算和受限脚本。本次在隔离环境执行：

5 * 25 + 15 * 100

返回值为 1625，退出码为 0。

E2B_API_URL=<SANDBOX_MANAGER_URL>
E2B_API_KEY=<SANDBOX_API_KEY>
KSADK_SANDBOX_TEMPLATE_ID=<TEMPLATE_ID>
KSADK_SANDBOX_TIMEOUT=120

4.6 Workspace

Workspace 根目录使用运行时持久卷：

KSADK_WORKSPACE_ROOT=/app/data/workspace

部署时显式挂载：

storage mount: /app/data
storage size: 20 Gi

这样 SQLite 会话数据库和 Workspace 文件不会随着 Pod 重启丢失。

4.7 Skills

本次创建了本地只读 Skill enterprise-runbook，用于校验 P1 运维检查清单。Linux local_process Skill Runtime 成功执行并生成工件。

当前账号没有可用的云端 Skill Space，且现有 Sandbox 模板不是包含 /home/ksadk/agent.py 的专用 Skill Runtime 镜像，因此不能把通用 Sandbox 成功等同于云端 Skill Runtime 成功。

生产环境应单独创建 Skill Space，并使用专用 Skill Runtime 模板；不要用通用代码沙箱冒充 Skill Runtime。

4.8 AI 搜索

AI 搜索用于补充外部时效信息，企业知识库用于回答受控事实。两类来源必须在回复中明确分区：

enterprise_knowledge  企业内部知识
external_web          外部公开网页
mcp                   实时业务指标
sandbox               计算结果
memory                用户偏好

五、本地验证

在发布前完成三层验证。

5.1 单元和契约测试

python -m pytest -q

测试覆盖：

  • 原名称扫描；

  • 依赖版本与根依赖契约；

  • Toolsets 合并与去重；

  • 环境状态不返回凭证；

  • AI 搜索结果规范化；

  • 测试知识和评测用例；

  • FastAPI 健康检查。

5.2 前端构建

cd frontend
npm ci
npm run build

5.3 本地容器

docker build -t enterprise-cloud-assistant:local .
docker run --rm -p 8122:8122 enterprise-cloud-assistant:local

验证：

curl http://127.0.0.1:8122/health

六、使用 AgentEngine CLI 构建并上传 KS3

本文选择 Serverless Code，不依赖 KCR。AgentEngine CLI 会生成 Linux 依赖、打包 ZIP，并使用 IAM AK/SK 自动上传 KS3。

agentengine build . \
  --mode code \
  --push \
  --region cn-beijing-6 \
  --no-cache \
  --output json

本次制品结果：

  • 制品类型：Code

  • ZIP 大小：79,536,294 字节

  • 上传状态：pushed=true

  • 目标：AgentEngine 管理的 KS3 Bucket

不要手工压缩目录。AgentEngine CLI 还会准备 Linux 依赖和运行入口，普通 ZIP 无法替代 Code Builder 产物。

七、在线调用与长对话验收

单轮调用可以使用 CLI：

agentengine agent invoke \
  --agent <AGENT_ID> \
  --message "企业 P1 故障应在多久内首次响应？" \
  --session enterprise-bp-session-a

企业验收不能只看单轮回答。本次实际完成两组会话：

  • 会话 A：12 轮，覆盖知识库、Sandbox、AI 搜索、MCP、Workspace、Skills 和记忆。

  • 会话 B：4 轮，覆盖计算复核、角色边界和会话上下文。

16 轮请求全部返回 HTTP 200。每轮记录：

  • HTTP 状态；

  • 响应耗时；

  • 问题和脱敏回答；

  • token 用量；

  • 相关运行日志和工具调用。

八、部署 AgentEngine 运行时

从构建元数据取得 KS3 路径，然后创建或更新运行时：

agentengine deploy . \
  --target serverless \
  --name enterprise-cloud-assistant \
  --region cn-beijing-6 \
  --account-id <ACCOUNT_ID> \
  --artifact-type Code \
  --ks3-path <KS3_ARTIFACT_PATH> \
  --env-file .env \
  --storage-size-gi 20 \
  --storage-mount-path /app/data \
  --observability \
  --enable-public-access \
  --auto-rollback

九、在线调用与长对话验收

单轮调用可以使用 CLI：

agentengine agent invoke \
  --agent <AGENT_ID> \
  --message "企业 P1 故障应在多久内首次响应？" \
  --session enterprise-bp-session-a

企业验收不能只看单轮回答。本次实际完成两组会话：

  • 会话 A：12 轮，覆盖知识库、Sandbox、AI 搜索、MCP、Workspace、Skills 和记忆。

  • 会话 B：4 轮，覆盖计算复核、角色边界和会话上下文。

16 轮请求全部返回 HTTP 200。每轮记录：

  • HTTP 状态；

  • 响应耗时；

  • 问题和脱敏回答；

  • token 用量；

  • 相关运行日志和工具调用。

十、可观测与评测

部署参数 --observability 会为运行时启用可观测能力。排障时按以下顺序定位：

  1. Session：确认用户会话和请求边界。

  2. Trace：确认一次请求的完整执行链。

  3. Observation：区分模型调用、工具调用和错误。

  4. Runtime Logs：定位启动、依赖、端口和底层 SDK 错误。

本次运行日志能够观察到：

  • Code Runtime 启动；

  • Agent 加载；

  • Uvicorn 监控端口；

  • 对话请求 HTTP 200；

  • Sandbox 创建与复用。

评测集包含 12 个用例，覆盖知识库、记忆、MCP、Sandbox、Workspace、Skill、AI 搜索、可观测和安全边界。

文档导读
上一篇：入门指引:快速部署智能体
下一篇：Agent开发平台
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈