Configuration

KsADK reads configuration from command-line options, project YAML, project .env, and optional global configuration. Values closer to the command usually take precedence for that run.

Precedence

command-line flags such as --model and --port.
environment variables exported in the shell.
values loaded from the project .env.
project YAML such as agentengine.yaml.
global developer defaults.

Use command-line flags for temporary experiments and project files for settings that should travel with the sample application.

Configuration Sources

Source	Typical file or command	Purpose
CLI option	`agentengine run --model glm-5.2`	one-off override
Project YAML	`agentengine.yaml`	framework, entry point, region, packaging hints
Project env	`.env`	local model credentials and provider URLs
Global config	managed by `agentengine config --global` style flows where supported	developer defaults across projects

Model Settings

The local runtime uses OpenAI-compatible settings for many examples:

.env

OPENAI_API_KEY=sk-test
OPENAI_BASE_URL=https://api.example.com/v1
OPENAI_MODEL_NAME=my-model

Use placeholder values in docs and tests. Use real values only in local .env files or CI secrets.

Common model-related variables:

Variable	Purpose
`OPENAI_API_KEY`	API key for an OpenAI-compatible provider
`OPENAI_BASE_URL`	provider base URL, usually ending in `/v1`
`OPENAI_MODEL_NAME`	default model for local runs
`MODEL_NAME`	compatibility alias used by some projects

When a request explicitly passes model, the local runtime may use it as a per-request override for supported runners.

Unified model policy and fallback

In hosted deployments the platform injects a unified model policy through AGENTENGINE_MODEL_POLICY_JSON, shared by Hermes, OpenClaw, and generic agents for primary / multimodal / fallback defaults. Explicit request parameters or explicit environment variables (such as HERMES_DEFAULT_MODEL / OPENCLAW_FALLBACK_MODEL) still take precedence over policy defaults. The conversation runtime automatically retries once with a fallback on recoverable errors such as timeout, rate limiting, 5xx, model unavailable, or permission/quota errors; 400 parameter errors, business errors, and tool errors are not swallowed.

For the full variable list and 0.6.7 reasoning / thinking-disable injection semantics, see Environment variables reference - Unified model policy and fallback.

Project Configuration

Project-level settings are stored in agentengine.yaml. ksadk.yaml and ksadk.yml are also detected for compatibility.

agentengine.yaml

name: my-agent
framework: langgraph
entry_point: agent.py
agent_variable: root_agent

.env

OPENAI_API_KEY=sk-test
OPENAI_BASE_URL=https://api.example.com/v1
OPENAI_MODEL_NAME=my-model

Common fields:

Field	Meaning	Example
`name`	display name and default runtime name	`my-agent`
`framework`	framework adapter	`adk`, `langchain`, `langgraph`, `deepagents`
`entry_point`	Python file loaded by the local runtime	`agent.py`
`agent_variable`	exported object name	`root_agent`
`region`	optional cloud region for deployment-shaped commands	`cn-beijing-6`

Prefer explicit project YAML in public samples. It is easier for contributors to review than relying on framework auto-detection.

Framework-Specific Notes

Framework	Recommended public config
ADK	set `framework: adk`, point `entry_point` to the module exporting the ADK agent
LangGraph	set `framework: langgraph`, export a compiled graph or provide the configured variable
LangChain	set `framework: langchain`, export the chain/runnable object
DeepAgents	set `framework: deepagents`, keep service-only startup code out of import side effects

If the project uses custom state or input preparation, keep those hooks in the configured entry module so the runner can import them consistently.

Config Commands

Interactive wizard:
```
agentengine config
```
Show effective settings:
```
agentengine config show
```

Set values non-interactively:

agentengine config set region=cn-beijing-6 OPENAI_MODEL_NAME=my-model

Switch the default model:
```
agentengine config model
```

Precedence And Local Overrides

Use CLI options for temporary overrides:

agentengine run . --model another-model
agentengine web . --model another-model

This is useful when comparing models without editing .env.

Runtime Feature Flags

Some capabilities are optional. Public examples should make these variables clearly optional:

Variable	Purpose
`KSADK_WORKSPACE_FILES_ENABLED`	enable workspace file routes
`KSADK_WORKSPACE_MAX_UPLOAD_BYTES`	set the upload limit for workspace files
`KSADK_LTM_BACKEND`	enable long-term memory backend integration
`KSADK_LTM_INDEX`	isolate long-term memory data
`KSADK_KB_DATASET_ID`	enable a knowledge-base integration
`KSADK_KB_TOP_K`	set knowledge retrieval count
`KSADK_BUILD_ENABLE_ATTACHMENT_OCR`	include OCR-related dependencies in build flows when intentionally needed

Leave these unset in the first quickstart unless the page is specifically about that capability.

Secrets And Files

Recommended local layout:

agentengine.yaml

agent.py

requirements.txt

.env

.gitignore

Recommended .gitignore entries:

.gitignore

.env
.agentengine/
dist/
build/
*.egg-info/

Never commit .pypirc, API keys, cookies, kubeconfig files, private registry credentials, customer data, local session databases, or uploaded files.

Public Documentation Rule

Do not publish real internal endpoints, access keys, cookies, kubeconfig paths, registry names, customer data, or private support URLs in examples. For public docs:

use https://api.example.com/v1 for placeholder provider URLs.
use sk-test or <YOUR_API_KEY> for placeholder tokens.
mark cloud settings as optional.
prefer local runtime examples over hosted infrastructure examples.

Configuration

On this page