Cloud Deployment to Kingsoft Cloud

This guide starts after a KsADK project works locally with agentengine run . -i or agentengine web .. It explains how to deploy that project as a hosted Agent on Kingsoft Cloud.

Choose A Target

serverless and the Code artifact type are the defaults. Choose Container only for a real image requirement, a package-size limit, or an intentional KCE deployment.

Prerequisites

1. Install KsADK with the extra for your framework. For LangGraph:

   pip install "ksadk[langgraph]"
   agentengine --version

2. A code project needs a working agentengine.yaml, entry point, and dependency manifest. A Codex ManagedRuntime has no entry point; it needs explicit framework: codex, artifact_type: ManagedRuntime, and runtime.name. Test locally first:

   agentengine run . -i

3. Prepare Kingsoft Cloud AK/SK credentials with permission for AgentEngine and the selected region. Code deployment also needs KS3 permission. Container deployment also needs a registry you can push to and a working local Docker installation. ManagedRuntime uses neither a KS3 code package nor local Docker.

4. Never commit AK/SK credentials, model keys, registry passwords, .env, prod.env, or .agentengine/. Commit only placeholder values in .env.example.

Configure Cloud Credentials And Runtime Variables

The interactive wizard is the simplest setup. It asks for model settings, cloud credentials, region, and optional registry information:

agentengine config

For automation, write cloud credentials to the current project's uncommitted .env:

agentengine config set \
  KSYUN_ACCESS_KEY=<your-access-key> \
  KSYUN_SECRET_KEY=<your-secret-key> \
  KSYUN_ACCOUNT_ID=<your-account-id> \
  KSYUN_REGION=cn-beijing-6

KSYUN_ACCOUNT_ID is optional when the SDK can resolve it from AK/SK. Put only runtime variables in a separate prod.env; do not put cloud AK/SK credentials in that file:

OPENAI_API_KEY=<your-model-api-key>
OPENAI_BASE_URL=https://api.example.com/v1
OPENAI_MODEL_NAME=<your-model-name>

Deploy Codex ManagedRuntime (new in 0.8)

Codex uses one agentengine.yaml and no agent.py. When runtime.version is locked explicitly, the CLI uses it directly. When omitted, it asks the server Runtime catalog for a default; a disabled catalog fails instead of guessing a version or falling back to CodeBuilder.

name: my-codex-agent
version: "1.0.0"
framework: codex
artifact_type: ManagedRuntime
runtime:
  name: codex
  version: "0.144.4"
model: kimi-k3
prompt: |
  You are a coding assistant.

Inspect the request first, then deploy:

agentengine deploy . --target serverless --region cn-beijing-6 --dry-run
agentengine deploy . --target serverless --region cn-beijing-6 --env-file ./prod.env

This sends an inline normalized manifest, Runtime name, version, and SHA-256. Do not pass --ks3-path, and do not use --push or --ks3-bucket for a ManagedRuntime; those Code-path options are rejected. Record the actual Runtime version and image digest returned by deployment. See YAML Is the Agent: Codex for the native-local workflow.

Deploy To Serverless

Start with a dry run to inspect the target, region, artifact type, network, and runtime environment without creating a remote Agent:

agentengine launch . \
  --target serverless \
  --region cn-beijing-6 \
  --env-file ./prod.env \
  --dry-run

Remove --dry-run after reviewing the plan:

agentengine launch . \
  --target serverless \
  --region cn-beijing-6 \
  --env-file ./prod.env

This creates a Code artifact, uploads it to KS3, and creates or updates the hosted Agent. Add --name my-agent to choose the name and --no-cache to force a new package.

Build And Deploy Separately

For CI or artifact review, build first and deploy the saved artifact reference:

agentengine build . --mode code --push --region cn-beijing-6
agentengine deploy . --target serverless --region cn-beijing-6 --env-file ./prod.env

Build metadata is stored below .agentengine/. Use --repackage or --no-cache when the current source must be packaged again.

Container And KCE

For Container mode, configure KCR_REGISTRY, KCR_USERNAME, and KCR_PASSWORD. Enterprise KCR and third-party registries require both username and password. Personal KCR may omit KCR_USERNAME; the SDK falls back to KSYUN_ACCOUNT_ID.

agentengine config set \
  KCR_REGISTRY=<registry-host/namespace> \
  KCR_USERNAME=<registry-username> \
  KCR_PASSWORD=<registry-password>

agentengine launch . \
  --target serverless \
  --artifact-type Container \
  --registry <registry-host/namespace> \
  --env-file ./prod.env

For KCE, use the same registry and a Container artifact, then choose a namespace:

agentengine launch . \
  --target kce \
  --artifact-type Container \
  --registry <registry-host/namespace> \
  --namespace default \
  --env-file ./prod.env

Network And Persistent Storage

New Agents allow public access by default. For VPC-only access, provide all three network identifiers together:

agentengine launch . \
  --target serverless \
  --disable-public-access \
  --enable-vpc-access \
  --vpc-id vpc-xxxx \
  --subnet-id subnet-xxxx \
  --security-group-id sg-xxxx \
  --availability-zone cn-beijing-6a \
  --env-file ./prod.env

Hermes and OpenClaw mount persistent storage by default. adk, langchain, langgraph, and deepagents mount storage only when you explicitly provide a mount path. For a persistent workspace or files across restarts:

agentengine launch . \
  --target serverless \
  --storage-size-gi 20 \
  --storage-mount-path /home/node/.agentengine \
  --env-file ./prod.env

Storage sizes range from 20 to 500 Gi. Use --no-storage to explicitly disable PVC storage.

Verify And Access

After deployment, inspect the hosted Agent and then open its dashboard:

agentengine agent list --region cn-beijing-6
agentengine agent status <agent-name-or-id> --region cn-beijing-6
agentengine dashboard open <agent-name-or-id>

Record the resulting Agent ID, name, and region with the deployment. When updating an Agent, public-access settings are retained unless you explicitly pass --enable-public-access or --disable-public-access.

Troubleshooting