全部文档
当前文档

热搜词推荐

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

共搜索到 0 条结果

暂无内容

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

文档中心

金山云星源AgentKit

查看更多结果
未找到含当前关键字的文档标题
页面目录
全部展开全部收起
未找到含该关键词的产品
文档中心 金山云星源AgentKit 快速入门 快速配置：.env文件参数

快速配置：.env文件参数

最近更新时间：2026-08-03 16:52:54

一、四类凭证

IAM AK/SK

IAM AK/SK 是金山云 OpenAPI 的身份凭证，由 AccessKey ID 和 AccessKey Secret 组成。

在本实践中，它用于：

  • AgentEngine CLI 调用控制面；

  • Code Builder 将 Code ZIP 上传到 KS3；

  • 知识库、记忆库等 AICP OpenAPI 调用。

当前控制台的真实入口是：

金山云主控制台
→ 访问控制
→ 人员管理 / 子用户
→ 搜索并进入目标子用户
→ 安全设置管理
→ 页面下方“用户 AccessKey”

步骤 1：进入“访问控制 > 子用户”，搜索并进入目标子用户。

步骤 2：在子用户详情页选择“安全设置管理”。

步骤 3：向下找到“用户 AccessKey”，选择“新建密钥”。

如果账号下已经存在多组 AK/SK，按以下顺序选择：

  1. 选择“启用中”的密钥；

  2. 选择与目标 AgentEngine、AICP 和 KS3 资源属于同一账号的密钥；

  3. 优先使用专门为该应用或环境创建的 IAM 子用户密钥；

  4. 检查密钥的最后使用时间，避免误用已经废弃但尚未删除的密钥；

  5. 确认该子用户具备 AgentEngine、AICP 和 KS3 所需权限；

  6. 不要使用历史“对象存储密钥”代替统一 IAM AK/SK。历史对象存储密钥仅能访问 KS3，不能保证可调用 AgentEngine 控制面。

AccessKey Secret 只在创建时显示一次。若 SK 丢失，不能从控制台再次查看，应新建密钥并轮换旧密钥。

环境变量：

KSYUN_ACCESS_KEY=<IAM_ACCESS_KEY_ID>
KSYUN_SECRET_KEY=<IAM_ACCESS_KEY_SECRET>

AgentKit API Key

AgentKit API Key 用于调用模型应用服务中的 MCP、AI 搜索和 Sandbox，不是 IAM AK/SK，也不是部署后访问运行时的 API Key。

在星源 AgentKit 平台左侧选择 API-Key 管理：

进入页面后，单击 新建：

新建时需要设置：

  • 名称；

  • 到期时间；

  • 描述；

  • 生效范围：MCP、AI 搜索服务、沙箱 Sandbox，可多选。

当列表中有多把 Key 时，优先选择：

  • 状态为“生效中”；

  • 生效范围覆盖当前 Agent 使用的服务；

  • 名称或描述能够对应当前应用和环境；

  • 尚未接近到期时间。

建议为“开发、测试、生产”分别创建专用 Key，不要让所有应用共用一把长期 Key。

AgentEngine 运行时 API Key

运行时 API Key 用于调用已经部署的 Agent Endpoint。

控制台创建运行时时，“入站身份认证”默认勾选 API Key，系统会自动创建并绑定。创建完成后，在运行时详情页查看。

先从左侧 Agent Engine > 运行时 进入运行时列表：

进入目标运行时详情页后，“快速调用”区域同时给出公网域名、内网域名和运行时 API Key：

它只用于请求运行时，不用于 CLI 上传 KS3，也不用于 MCP、AI 搜索或 Sandbox。

模型 API Key

模型 API Key 用于调用 OpenAI 兼容模型服务。它与 IAM AK/SK、AgentKit API Key、运行时 API Key 都不同。

常用配置：

OPENAI_API_KEY=<MODEL_API_KEY>
OPENAI_BASE_URL=<OPENAI_COMPATIBLE_BASE_URL>
OPENAI_MODEL_NAME=<MODEL_NAME>

若使用星流平台模型 API 服务，可从模型 API 服务的 API Key 管理和模型广场获取 Key、模型名称及对应接入信息。

二、控制台数据

2.1 部署基础数据

所需数据

控制台位置或获取方式

填入位置

注意事项

Account ID / UID

金山云控制台右上角头像，查看并复制 UID

--account-id、KSYUN_ACCOUNT_ID

必须与 AK/SK 对应的账号一致；不要填登录名或手机号

Region

AgentEngine 运行时创建页、运行时详情或 CLI 配置中的默认区域

--region、KSYUN_REGION

使用地域代码，例如 cn-beijing-6

运行时名称

模型应用服务 → Agent Engine 运行时

--name

同一账号下不可重复；官方限制为 4-64 个字符

运行时 ID

Agent Engine 运行时列表或详情页

状态查询、控制台直达

创建成功后由平台生成

运行时 Endpoint

目标运行时详情页 → 概览

SDK 或 HTTP 客户端 Base URL

公网和 VPC 内网地址不同，必须从当前运行时详情页复制

运行时 API Key

目标运行时详情页 → 入站身份认证

调用请求认证

平台创建并绑定；不要与 AgentKit API Key 混用

KS3 Code ZIP 路径

agentengine build --push --output json 的输出，或创建运行时时从 KS3 选择

--ks3-path

必须是 AgentEngine CLI / Code Builder 生成的制品，不能用普通手工 ZIP

KS3 Bucket

KS3 控制台，或 CLI 自动创建的 agentengine-{account_id}-{region}

--ks3-bucket

Bucket 名称全局唯一；未指定时 CLI 按规则生成

所属项目

创建运行时页面 → 高级配置 → 所属项目

控制台配置

默认为“默认项目”

账号 UID 位于金山云主控制台首页右侧账号卡片，单击右侧复制图标即可：

Region 由 AgentKit 页面顶部地域选择器确定，创建运行时和上传 KS3 制品时应保持一致：

KS3 在金山云主控制台中显示为“对象存储”：

创建运行时时，基础数据对应下图两个区域：

2.2 平台组件数据

所需数据

控制台位置

对应变量或代码引用

知识库数据集 ID

模型应用服务 → 知识库 → 目标数据集详情

KSADK_KB_DATASET_ID

知识库文档状态

知识库 → 目标数据集 → 文档管理

无固定变量

记忆库 Namespace / 实例 ID

模型应用服务 → 记忆库 → 目标实例详情

KSADK_LTM_NAMESPACE

MCP Server ID / Endpoint

模型应用服务 → MCP → MCP 管理 → 目标服务详情

MCP 配置或工具加载参数

Sandbox 模板 ID

模型应用服务 → 沙箱 Sandbox → 模板管理 → 目标模板详情

KSADK_SANDBOX_TEMPLATE_ID

Sandbox API Key

模型应用服务 → API-Key 管理

E2B_API_KEY

Sandbox Manager URL

沙箱接入说明、模板详情或平台提供的环境配置

E2B_API_URL

AgentKit API Key

模型应用服务 → API-Key 管理

MCP、AI 搜索、Sandbox 认证

各组件的一级入口均在 AgentKit 左侧导航栏，红框位置分别对应 MCP、知识库、记忆库和 Sandbox：

创建运行时时，在“组件配置”区域选择已经创建的知识库、记忆库、沙箱和会话管理实例：

2.3 .env 中不是从控制台复制的值

以下值通常是应用或 SDK 配置，不应误认为控制台资源 ID：

变量

含义

推荐值或来源

KSADK_KB_SCHEME

知识库接口协议

公网 https；内网 http

KSADK_KB_TOP_K

单次知识库检索返回的切片数

默认 20，可按召回质量调整

KSADK_LTM_BACKEND

长期记忆后端

云端使用 sdk

KSADK_SANDBOX_BACKEND

沙箱后端类型

当前实践使用 e2b

KSADK_SANDBOX_TIMEOUT

单次沙箱执行超时秒数

含冷启动，实践建议 120；KSADK 0.6.8 工具可能更长

PORT

Code Runtime 实际端口

本次 KSADK 0.6.8 Code 制品为 8080

AGENTENGINE_UI_DIR

KSADK 本地会话数据库和 Workspace 的父目录

仅在需要把会话文件放入已挂载目录时设置

运行时创建页的“高级配置”用于设置入站认证、可观测、环境变量、所属项目和可见权限：

三、Endpoint

3.1 AICP / AgentEngine 控制面 / 知识库 / 记忆库

KSADK 0.6.8 中可以确认以下地址：

模式

Endpoint

Scheme

适用场景

公网

aicp.api.ksyun.com

https

本地电脑、非金山云内网环境

内网

aicp.inner.sdns.ksyun.com

http

金山云内网环境

公网环境通常不需要覆盖控制面地址，内网环境使用当前确认的Endpoint时，显示设置：

AGENTENGINE_SERVER_URL=http://aicp.inner.sdns.ksyun.com

知识库和记忆库也可以分别覆盖：

# 公网
KSADK_KB_ENDPOINT=aicp.api.ksyun.com
KSADK_KB_SCHEME=https
KSADK_LTM_ENDPOINT=aicp.api.ksyun.com
KSADK_LTM_SCHEME=https

# 内网
KSADK_KB_ENDPOINT=aicp.inner.sdns.ksyun.com
KSADK_KB_SCHEME=http
KSADK_LTM_ENDPOINT=aicp.inner.sdns.ksyun.com
KSADK_LTM_SCHEME=http

不要只替换域名而保留错误协议。当前内网示例使用 http，公网使用 https。

3.2 KS3 公网 / 内网 Endpoint

KS3 Endpoint 与 Bucket 所在 Region 对应。根据 2026-05-06 更新的官方文档，可确认 9 组公网 / 内网地址：

Region

公网 Endpoint

内网 Endpoint

中国（北京）

ks3-cn-beijing.ksyuncs.com

ks3-cn-beijing-internal.ksyuncs.com

中国（上海）

ks3-cn-shanghai.ksyuncs.com

ks3-cn-shanghai-internal.ksyuncs.com

中国（广州）

ks3-cn-guangzhou.ksyuncs.com

ks3-cn-guangzhou-internal.ksyuncs.com

中国（青海）

ks3-cn-qinghai.ksyuncs.com

ks3-cn-qinghai-internal.ksyuncs.com

中国（庆阳）

ks3-cn-qingyang.ksyuncs.com

ks3-cn-qingyang-internal.ksyuncs.com

中国（宁夏）

ks3-cn-ningxia.ksyuncs.com

ks3-cn-ningxia-internal.ksyuncs.com

新加坡

ks3-sgp.ksyuncs.com

ks3-sgp-internal.ksyuncs.com

金融专区（北京）

ks3-jr-beijing.ksyuncs.com

ks3-jr-beijing-internal.ksyuncs.com

金融专区（上海）

ks3-jr-shanghai.ksyuncs.com

ks3-jr-shanghai-internal.ksyuncs.com

使用规则：

  • 本地上传 Code ZIP 时通常走公网 Endpoint；

  • 金山云同地域云资源访问 KS3 时可走内网 Endpoint；

  • 内网访问要求访问方与 KS3 处于支持互通的网络和地域；

  • Bucket 资源地址一般为 <Bucket>.<Endpoint>/<Object>；

  • CLI 0.6.8 支持 KS3_ENDPOINT_MODE=auto|internal|public，auto 会探测并优先选择可达地址；

3.3 Sandbox、MCP、模型与运行时 Endpoint

这些 Endpoint 不能靠固定字符串批量推导：

运行时详情页会分别显示公网域名和内网域名；是否生成内网域名取决于创建时的网络配置：

下图中的 VPC、子网和安全组决定运行时能否通过私网访问，不能只把公网域名手工改成“内网域名”：

服务

公网 / 内网处理方式

Sandbox Manager

公网示例为 https://mgr.cn-beijing-6.sandbox.ksyun.com；公开文档和 KSADK 0.6.8 未给出可通用于所有账号的固定内网域名，应从沙箱接入说明、模板详情或运行环境注入值获取

自定义 MCP

Endpoint 由 MCP 服务部署方式决定；在 MCP 管理详情页复制，内网服务还需满足 Agent 运行时的 VPC 连通性

模型 Base URL

由模型供应商或星流模型 API 服务提供；公网和专线/VPC 地址不能混用

Agent Runtime Endpoint

平台按运行时生成。公网访问会创建并绑定公网入口；内网访问需要选择 VPC、子网和安全组。两种地址都应从运行时详情页复制

VPC OpenAPI

KSADK 0.6.8 在特定内网鉴权错误下会回退 vpc.inner.api.ksyun.com（HTTP）；该地址是 CLI 查询子网信息的控制面地址，不是 Agent 的业务访问地址

四、agentengine build 参数说明

本文实践命令：

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

参数

含义

什么时候使用

.

Agent 项目根目录

当前目录就是项目根目录时使用

--mode code

构建 Code 制品：收集 Linux 依赖并生成 ZIP

Serverless Code 路线使用；不需要 KCR

--push

构建完成后将 ZIP 上传到 KS3

需要随后部署到 AgentEngine 时使用

--region

KS3 制品所在地域

应与计划部署的运行时地域一致

--no-cache

忽略已有 ZIP 和构建缓存，完整重建

修改依赖、构建入口或怀疑缓存污染时使用

--repackage

复用依赖缓存，只重新打包当前代码和 runtime

只改业务代码、希望缩短构建时间时使用

--ks3-bucket

指定上传 Bucket

不希望使用 CLI 默认 Bucket 时设置

--output json

以 JSON 输出构建结果

便于取得 KS3 路径、制品大小和 pushed 状态

五、agentengine deploy 参数说明

控制台字段与 CLI 参数的对应关系可先看三张实拍图：

  • 基本信息、代码包、KS3 路径、实例规格：

  • 公网/内网访问及知识库、记忆库、沙箱、会话管理：

  • 入站 API Key、可观测、环境变量、项目和权限：

本文实践命令：

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

参数

含义

实践建议

--target serverless

部署到 AgentEngine 托管 Serverless 运行时

本文固定使用该目标

--name

云端运行时名称

使用脱敏、可区分环境的名称；同账号下不可重复

--region

运行时所在地域

与 KS3 制品和依赖资源保持一致

--account-id

与 IAM AK/SK 对应的金山云账号 UID

从控制台头像复制，不要手工猜测

--artifact-type Code

使用 KS3 上的 Code ZIP 部署

与 Container 镜像模式二选一；Code 模式不需要 KCR

--ks3-path

已上传 Code ZIP 的 KS3 路径

从 build --push --output json 原样复制

--ks3-bucket

KS3 Bucket 名称

只有需要覆盖默认 Bucket 时设置

--env-file .env

读取 .env 或 JSON 对象，将变量透传到运行时

文件中不得混入无关本地变量；不得提交真实密钥

--env KEY=VALUE

追加单个运行时环境变量，可重复传入

临时覆盖少量变量时使用，避免把密钥直接写进命令历史

--port

通用服务端口参数，CLI 帮助默认 8000

Code Runtime 的真实入口仍以制品入口和 PORT 环境变量为准；本次 0.6.8 实测需 PORT=8080

--storage-size-gi 20

创建 20 Gi 持久卷

只有确实需要持久数据时使用

--storage-mount-path /app/data

将持久卷挂载到容器内 /app/data

LangGraph 等框架默认不自动挂盘，必须显式指定

--no-storage

禁用默认持久卷

应用完全无状态时使用

--observability

启用运行时可观测能力

官方控制台默认启用，生产建议保留

--enable-public-access

开启公网访问

平台将创建公网入口；对外服务需要配合 API Key

--disable-public-access

关闭公网访问

仅允许内网访问时使用

--enable-vpc-access

开启 VPC 私网访问

需要同时配置 VPC、子网和安全组

--vpc-id

VPC ID

开启 VPC 访问时必填

--subnet-id

子网 ID

开启 VPC 访问时必填

--security-group-id

安全组 ID

开启 VPC 访问时必填

--availability-zone

可用区

可选；CLI 可尝试从子网推断，失败时应显式指定

--auto-rollback

部署失败时回滚到上一版本

更新生产运行时时建议启用

--no-version

部署成功后不创建版本快照

生产环境一般不要使用，否则不利于回滚

--dry-run

只生成配置和请求，不执行部署

首次部署或排查 400 参数错误时先运行

--output json

JSON 格式输出部署结果

便于自动化保存运行时 ID、Endpoint 和状态

六、agentengine launch 与分步部署

launch 等价于“一次执行 Build + Push + Deploy”：

agentengine launch . \
  --target serverless \
  --account-id <ACCOUNT_ID> \
  --artifact-type Code \
  --region cn-beijing-6 \
  --observability \
  --auto-rollback \
  --output json

适合：

  • 首次部署；

  • 参数已经稳定；

  • 希望一次得到构建和部署结果。

分开执行 build 和 deploy 适合：

  • 需要先复核 Code ZIP 和 KS3 路径；

  • 需要保存构建证据；

  • 同一制品要部署到多个环境；

  • 需要排查构建失败还是运行时创建失败。

七、AgentEngine CLI 命令参考

本节基于 ksadk-python 仓库提交
2a6f94a
的源码整理，对应 ksadk 0.7.0。后续版本应以安装版本执行
agentengine --help 和 agentengine <command> --help 的结果为准。

7.1 命令入口

源码在 pyproject.toml 中把两个命令都注册到同一个入口：

[project.scripts]
agentengine = "ksadk.cli:main"
ksadk = "ksadk.cli:main"

因此 agentengine 和 ksadk 是同一个 CLI 的两个命令名。面向客户的文档统一使用

agentengine。

全局语法：

agentengine [--output pretty|json] [--no-color] [--dry-run] <command> [options]

全局参数

可选值或行为

--output

pretty、json

--no-color

禁用彩色输出

--dry-run

只生成计划或请求，不执行实际操作

--version

显示 CLI 版本

-h, --help

显示帮助

7.2 客户可见命令

命令

用法

作用

init

agentengine init [PROJECT_NAME]

创建项目，或使用 --from-agent 包装已有 Agent

run

agentengine run [AGENT_DIR]

在本地运行 Agent；-i 进入交互式 TUI

web

agentengine web [AGENT_DIR]

启动本地 Invoke UI

build

agentengine build [AGENT_DIR]

构建 Code ZIP 或容器镜像；配合 --push 上传 KS3 或推送镜像

deploy

agentengine deploy [AGENT_DIR]

创建或更新云端 Agent；没有可复用制品时也会执行构建与上传

launch

agentengine launch [AGENT_DIR]

一次完成构建、上传和部署

config

agentengine config <wizard|show|set|model>

配置项目、环境变量和默认模型

agent

agentengine agent <list|status|invoke|delete>

查询、调用和删除云端 Agent

files

agentengine files <list|upload|download|delete|push|pull>

管理运行时 Workspace 文件

dashboard

agentengine dashboard <open|share>

打开 Dashboard，或管理 Dashboard 分享

mcp

agentengine mcp <build|deploy|list|status|delete>

构建、部署和管理 MCP 资源

version

agentengine version <list|release|rollback>

查询、发布和回滚 Agent 版本

a2a

agentengine a2a <serve|card>

启动 A2A 服务或输出 Agent Card

completion

agentengine completion <bash|zsh|install>

生成或安装 Shell 补全

openclaw

agentengine openclaw <subcommand>

OpenClaw 专用网关、渠道和部署命令

hermes

agentengine hermes <subcommand>

Hermes 专用部署和资源管理命令

其中 model、status、invoke、delete 和 destroy 仍保留在源码中，但被标记为

隐藏兼容命令。新文档应分别使用 config model、agent status、agent invoke 和

agent delete，不把隐藏命令作为客户主入口。

7.3 核心工作流

# 创建 LangGraph 项目
agentengine init demo-agent --framework langgraph

# 本地运行
agentengine run ./demo-agent --interactive

# 启动本地 Invoke UI
agentengine web ./demo-agent --no-open

# 构建 Code ZIP 并上传 KS3
agentengine build ./demo-agent --mode code --push

# 使用已有 KS3 制品部署
agentengine deploy ./demo-agent \
  --target serverless \
  --artifact-type Code \
  --ks3-path <KS3_ARTIFACT_PATH>

# 一次完成构建、上传和部署
agentengine launch ./demo-agent \
  --target serverless \
  --artifact-type Code

build、deploy 和 launch 的关系：

命令

构建

上传

创建或更新运行时

build --push

是

是

否

deploy --ks3-path <PATH>

复用已有制品

否

是

deploy（没有可复用制品）

是

是

是

launch

是

是

是

7.4 枚举型参数

下表只列源码中通过 click.Choice 明确限制的可选值；region、资源 ID、路径和名称等

自由文本参数不应伪造枚举值。

命令或范围

参数

可选值

默认值

全局及多数命令

--output

pretty、json

pretty

init

--framework

adk、langchain、langgraph、deepagents、openclaw、hermes

langgraph

build

--mode

code、container

code

deploy、launch

--target

serverless、kcf、kce

serverless

deploy、launch

--artifact-type

Code、Container

Serverless 默认为 Code

deploy、launch

--ui-profile

auto、adk、langchain、openclaw、hermes、custom

auto 或按配置解析

config model

--framework

auto、openclaw、hermes、generic

auto

agent invoke

--transport

auto、chat、native

auto

兼容命令 invoke

--api-format

auto、responses、chat_completions

auto

dashboard share list

--type

private、share

未指定

dashboard share list

--status

active、revoked

未指定

mcp build、mcp deploy

--artifact-type

Code、Container

Code

completion install

--shell

bash、zsh、auto

auto

openclaw gateway logs

--log-type

stdout、log

stdout

openclaw repair

--action

doctor-fix

doctor-fix

openclaw channel

--channel

weixin、feishu、wps-xiezuo

部分子命令必填

openclaw channel connect

--dm-policy

disabled、open、pairing、allowlist

pairing

openclaw channel connect

--group-policy

open、allowlist

open

openclaw deploy

--security-profile

relaxed、strict、strictest

未指定

openclaw deploy

--memory-system

openclaw_default、mem0

未指定

7.5 源码依据

文档导读
上一篇：进阶入门:智能体开发
下一篇：Agent开发平台
纯净模式常规模式

纯净模式

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