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. Your project needs a working agentengine.yaml, entry point, and dependency manifest. Test it first:

   agentengine run . -i

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

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 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