Configuration File Reference

agentkit.yaml is the core configuration file for your Agent. It contains all runtime parameters. This document explains what each configuration field does.

Configuration system overview

AgentKit uses a two-level configuration architecture:

Config file	Location	Purpose
Project config	`./agentkit.yaml`	Project-level config. Each Agent project is independent.
Global config	`~/.agentkit/config.yaml`	User-level config shared across projects (for example, Volcengine credentials).

Precedence:

Environment variables > Project config > Global config > Defaults

File structure

The project config file has three sections:

yaml

common:
  # Base config (shared by all launch types)
  agent_name: my_agent
  entry_point: my_agent.py
  language: Python
  launch_type: cloud
  runtime_envs: {}           # App-level environment variables

launch_types:
  local:
    # Local-only settings
  hybrid:
    # Hybrid-only settings
  cloud:
    # Cloud-only settings

docker_build:
  # Docker build config (optional)
  base_image: python:3.12-slim
  build_script: scripts/setup.sh

The three sections:

common - shared configuration for all deployment modes
launch_types - mode-specific configuration for different deployment modes
docker_build - optional Docker build customization

`common`

Base configuration required by all deployment modes.

Example

yaml

common:
  agent_name: my_weather_agent        # Agent name (required)
  entry_point: my_weather_agent.py    # Entry file (required)
  description: Weather query agent    # Description (optional)
  language: Python                    # Programming language
  language_version: '3.12'            # Language version
  dependencies_file: requirements.txt  # Dependency file
  launch_type: cloud                  # Launch type
  runtime_envs:                       # App-level env vars (shared by all launch types)
    LOG_LEVEL: info

Fields

`agent_name` (required)

The Agent name

📝 What it does: gives your Agent a name
✅ Rules: only letters, numbers, _, and -
🎯 Used for:
- Docker image name
- prefix for the cloud Runtime name
- default image repository name

Examples:

yaml

agent_name: weather_agent           # Recommended: simple and clear
agent_name: financial-analyzer-v2   # OK: includes a version
agent_name: customer_support_bot    # OK: descriptive

`entry_point` (required)

The entry file for your Agent code

📝 What it does: specifies which file to run
✅ Rules: must end with .py, .go, or .sh
🎯 Used for: the container runs this file on startup

Examples:

yaml

# Python project
entry_point: app.py
entry_point: server.py

# Go project
entry_point: main.go
entry_point: cmd/server/main.go

# Custom startup script
entry_point: start.sh

`description` (optional)

A description of the Agent

📝 What it does: briefly explains what the Agent does
✅ Rules: any text
🎯 Used for: helping teammates understand the purpose

Examples:

yaml

description: "Weather query agent for major cities nationwide"
description: "Customer support assistant for common questions"

`language` (optional)

Programming language

📝 What it does: declares the language used by the project
✅ Options: Python, Golang
✅ Default: Python
🎯 Used for: choosing the Dockerfile template and build workflow

Examples:

yaml

language: Python    # Python project
language: Golang    # Go project

`language_version` (optional)

Language runtime version

📝 What it does: specifies the language version
✅ Python supported: 3.10, 3.11, 3.12, 3.13
✅ Golang supported: 1.24
✅ Default: Python 3.12, Golang 1.24

Examples:

yaml

# Python project
language: Python
language_version: '3.12'

# Go project
language: Golang
language_version: '1.24'

⚠️ Note: python_version is deprecated. Use language_version instead.

`dependencies_file` (optional)

Dependency list file

📝 What it does: sets the path to your dependency file
✅ Default: requirements.txt for Python projects; go.mod for Go projects
🎯 Used for: installing dependencies during build

Examples:

yaml

# Python project
dependencies_file: requirements.txt
dependencies_file: requirements/prod.txt

# Go project
dependencies_file: go.mod

`launch_type` (required)

Deployment and runtime mode

📝 What it does: selects where to build and run
✅ Options: local, hybrid, cloud

Mode	Best for	Build location	Run location
`local`	local development & debugging	your machine	your machine
`hybrid`	transition phase	your machine	cloud platform
`cloud`	production	cloud platform	cloud platform

Examples:

yaml

launch_type: local   # local development
launch_type: hybrid  # build locally + deploy to cloud
launch_type: cloud   # production (recommended)

`cloud_provider` (optional)

Cloud provider (platform service provider)

📝 What it does: choose whether platform services use Volcano Engine (China) or BytePlus (Overseas)
✅ Options: volcengine, byteplus
✅ Default: volcengine
🎯 Used for:
- affects default region, endpoint, and credential namespace
- affects the default base image used for auto-generated Dockerfiles (when docker_build.base_image is not explicitly set)

Precedence (highest to lowest):

Environment variables > Project config (agentkit.yaml) > Global config (~/.agentkit/config.yaml) > Defaults

How to configure:

yaml

# 1) Project config (recommended: put it in agentkit.yaml)
common:
  cloud_provider: byteplus

bash

# 1.1) Project config (write to agentkit.yaml via non-interactive command)
agentkit config --cloud_provider byteplus

yaml

# 2) Global config (applies across projects)
defaults:
  cloud_provider: byteplus

bash

# 3) Environment variables (temporary override)
export CLOUD_PROVIDER=byteplus

`runtime_envs` (optional)

App-level environment variables

📝 What it does: defines environment variables shared by all deployment modes
🎯 Used for: common configuration such as log level
⚠️ Precedence: policy-level runtime_envs override variables with the same name defined at the app level

Example:

yaml

common:
  runtime_envs:
    LOG_LEVEL: info
    APP_ENV: production

Local launch type

Build and run on local Docker. Best for development and debugging.

Example

yaml

launch_types:
  local:
    image_tag: latest                  # Image tag
    invoke_port: 8000                  # App port
    container_name: my_agent           # Container name (optional)
    runtime_envs:                      # Policy-level env vars
      MODEL_AGENT_API_KEY: xxx
    ports:                             # Port mappings
      - "8000:8000"
    restart_policy: unless-stopped     # Restart policy
    memory_limit: 1g                   # Memory limit
    cpu_limit: '1'                     # CPU limit

Fields

`image_tag`

Image version tag

Default: latest
Purpose: distinguishes different image versions
Examples: latest, v1.0, dev

`invoke_port`

The port your Agent listens on

Default: 8000
Purpose: sets which port the app listens on
❗ Must match the port used in your code

`container_name`

Docker container name

Default: uses agent_name
Purpose: assigns a name to the container
Can be omitted; a name will be generated automatically

`runtime_envs`

Policy-level runtime environment variables

Environment variables passed into the container, such as API keys and configuration parameters. They are merged with common.runtime_envs; variables with the same name override the app-level ones.

yaml

runtime_envs:
  MODEL_AGENT_API_KEY: your_api_key  # Model API key
  DEBUG: 'true'                      # Enable debugging
  LOG_LEVEL: debug                   # Override LOG_LEVEL from common

`ports`

Port mappings

Maps container ports to host ports using host_port:container_port.

yaml

ports:
  - "8080:8000"  # Host 8080 maps to container 8000
  - "9090:9090"  # Monitoring port

`volumes`

Volume mounts

Mounts host directories into the container using host_path:container_path.

yaml

volumes:
  - "./data:/app/data"      # Data directory
  - "./logs:/app/logs"      # Log directory

`restart_policy`

Container restart policy

Default: unless-stopped
Options:
- no - do not restart
- on-failure - restart on failures
- always - always restart
- unless-stopped - restart unless manually stopped

`memory_limit` / `cpu_limit`

Resource limits

Limits the resources a container can use, preventing it from consuming too much.

yaml

memory_limit: 2g    # Limit to 2GB memory
cpu_limit: '1'      # Limit to 1 CPU core

Auto-managed fields

The following fields are generated and managed by the CLI; you do not need to set them manually:

Field	Description
`container_id`	Container ID after deployment
`image_id`	Image ID after build
`build_timestamp`	Build time
`deploy_timestamp`	Deployment time
`full_image_name`	Full image name (e.g. `my-agent:latest`)

Cloud launch type

Build and run on Volcengine. Best for production.

Example

yaml

launch_types:
  cloud:
    region: cn-beijing                       # Region
    image_tag: "{{timestamp}}"               # Image tag (template variables supported)

    # TOS (object storage) settings
    tos_bucket: Auto                         # Auto-create bucket

    # Container Registry settings
    cr_instance_name: Auto                   # CR instance name (Auto = auto-create)
    cr_namespace_name: agentkit              # CR namespace
    cr_repo_name: ""                         # CR repo name (empty = use agent_name)

    # Runtime settings
    runtime_name: Auto                       # Runtime name
    runtime_role_name: Auto                  # IAM role name
    runtime_apikey_name: Auto                # API key secret name

    # Environment variables
    runtime_envs:
      MODEL_AGENT_API_KEY: xxx               # Model API key
      MODEL_AGENT_NAME: ep-xxx               # Model endpoint

Template variables

Cloud mode supports template variables, rendered automatically during build/deploy:

Variable	Description	Example value
	Current timestamp (YYYYMMDDHHmmss)	`20251128153042`
	Volcengine account ID	`2100123456`

Examples:

yaml

image_tag: "{{timestamp}}"                               # Unique tag for each build
cr_instance_name: "agentkit-platform-{{account_id}}"     # Account-isolated CR instance
tos_bucket: "agentkit-platform-{{account_id}}"           # Account-isolated bucket

The `Auto` keyword

When a value is Auto, the CLI will automatically create or manage the corresponding resource:

Field	Auto behavior
`tos_bucket`	Auto-create bucket `agentkit-platform-`
`cr_instance_name`	Auto-create CR instance `agentkit-platform-`
`runtime_name`	Auto-create Runtime
`runtime_role_name`	Auto-create IAM role
`runtime_apikey_name`	Auto-create API key secret

Fields

`region`

Volcengine region

Default: cn-beijing
Purpose: selects the geographic location where the service runs
Options: cn-beijing (currently only Beijing is supported)

💡 Tip: choose the region closest to your users to reduce latency.

`image_tag`

Image version tag

Default: (generates a unique tag each build)
Purpose: distinguishes different versions
Examples: , latest, v1.0.0

yaml

# Option 1: use a timestamp (recommended; ensures uniqueness)
image_tag: "{{timestamp}}"

# Option 2: fixed version
image_tag: v1.0.0

# Option 3: use latest (not recommended for production)
image_tag: latest

`tos_bucket`

Object storage bucket

Default: Auto (auto-create)
Purpose: stores the source code archive (for cloud builds)
Security note: tos_bucket must belong to your current account. If you set another person's bucket name (e.g. a public read-write bucket), the CLI will block uploads and ask you to change it.

yaml

# Auto-create (recommended)
tos_bucket: Auto

# Use an existing bucket
tos_bucket: my-existing-bucket

`cr_instance_name`

Container Registry instance name

Default: Auto (auto-create)
Purpose: selects which CR instance stores your Docker images

yaml

# Auto-create
cr_instance_name: Auto

# Use an existing instance
cr_instance_name: my-existing-cr

`cr_namespace_name`

CR namespace

Default: agentkit
Purpose: organizes and manages images
Auto-create: created automatically if missing

`cr_repo_name`

CR repository name

Default: empty (uses agent_name)
Purpose: the repository that stores the image
Auto-create: created automatically if missing

`runtime_name` / `runtime_role_name` / `runtime_apikey_name`

Runtime-related settings

Default: Auto (auto-create)
Purpose: manages the cloud runtime instance and its authentication

yaml

runtime_name: Auto           # Runtime name
runtime_role_name: Auto      # IAM role
runtime_apikey_name: Auto    # API key secret name

`runtime_envs`

Policy-level runtime environment variables

Configuration required by the Agent at runtime. The most important values are model API credentials. They are merged with common.runtime_envs.

Required:

yaml

runtime_envs:
  MODEL_AGENT_API_KEY: xxx  # Volcano Ark API key
  MODEL_AGENT_NAME: ep-xxx  # Volcano Ark endpoint ID

Optional (enhanced capabilities):

yaml

runtime_envs:
  # Base settings
  MODEL_AGENT_API_KEY: xxx
  MODEL_AGENT_NAME: ep-xxx

  # Observability (logs, metrics, tracing)
  OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY: xxx
  OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT: http://apmplus-cn-beijing.volces.com:4317
  OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME: my_agent

  # Other settings
  DEBUG: 'true'     # Enable debug mode
  LOG_LEVEL: info   # Set log level

`build_timeout`

Build timeout

Default: 3600 (seconds)
Purpose: maximum wait time for a cloud build

Auto-managed fields

The following fields are generated and managed by the CLI; you do not need to set them manually:

TOS storage-related

Field	Description
`tos_prefix`	Object storage prefix (default `agentkit-builds`)
`tos_object_key`	Storage path for the code package
`tos_object_url`	URL for the code package

Code Pipeline build-related

Field	Description
`cp_workspace_name`	Build workspace name
`cp_pipeline_name`	Build pipeline name
`cp_pipeline_id`	Pipeline ID

Image-related

Field	Description
`cr_region`	Image registry region
`cr_image_full_url`	Full image URL

Runtime-related

Field	Description
`runtime_id`	Runtime instance ID
`runtime_endpoint`	Application access URL
`runtime_apikey`	Runtime API key
`build_timestamp`	Build time
`deploy_timestamp`	Deployment time

Hybrid launch type

Build locally and run in the cloud. This is useful during development and debugging: you can build images quickly on your machine and then run them on the cloud.

Example

yaml

launch_types:
  hybrid:
    region: cn-beijing                       # Cloud region
    image_tag: "{{timestamp}}"               # Image tag (template variables supported)

    # Container Registry settings
    cr_instance_name: Auto                   # CR instance name
    cr_namespace_name: agentkit              # CR namespace
    cr_repo_name: ""                         # CR repo name

    # Runtime settings
    runtime_name: Auto                       # Runtime name
    runtime_role_name: Auto                  # IAM role name
    runtime_apikey_name: Auto                # API key secret name

    # Environment variables
    runtime_envs:
      MODEL_AGENT_API_KEY: xxx               # Model API key
      MODEL_AGENT_NAME: ep-xxx               # Model endpoint

Differences from Cloud mode

Item	Hybrid	Cloud
Build location	Local Docker	Cloud Code Pipeline
TOS settings	Not required	Required (stores the code package)
Build speed	Fast (local)	Slower (upload + cloud build)
Best for	Development & debugging	Production

Fields

Hybrid mode is largely the same as Cloud mode, but does not require TOS-related settings (because local builds do not upload a source archive).

`region`

Volcengine region

Default: cn-beijing
Purpose: selects the geographic location where the cloud service runs

`image_tag`

Image version tag

Default:
Purpose: distinguishes different image versions
Template variables supported

`cr_instance_name` / `cr_namespace_name` / `cr_repo_name`

Container Registry settings

Same as Cloud mode. Used to store the locally built image.

yaml

cr_instance_name: Auto          # Auto-create CR instance
cr_namespace_name: agentkit     # Namespace
cr_repo_name: ""                # Repo name (empty = use agent_name)

`runtime_name` / `runtime_role_name` / `runtime_apikey_name`

Runtime settings

Same as Cloud mode. Used to manage the cloud runtime instance.

`runtime_envs`

Policy-level runtime environment variables

Same as Cloud mode. Environment variables passed to the cloud runtime.

Auto-managed fields

The following fields are generated and managed by the CLI; you do not need to set them manually:

Field	Description
`image_id`	Image ID built locally
`build_timestamp`	Build time
`full_image_name`	Full image name
`cr_image_full_url`	Full image URL in CR
`runtime_id`	Runtime instance ID
`runtime_endpoint`	Application access URL
`runtime_apikey`	Runtime API key

`docker_build`

Customize the Docker build process. Supports custom base images, build scripts, and more.

Example

yaml

docker_build:
  # Python project - string form
  base_image: "python:3.12-slim"

  # Custom build script
  build_script: "scripts/setup.sh"

  # Force regenerate Dockerfile
  regenerate_dockerfile: false

  # Target platform (cross-platform builds)
  platform: "linux/amd64"

Multi-stage build for Go projects:

yaml

docker_build:
  base_image:
    builder: "golang:1.24-alpine"    # Builder stage image
    runtime: "alpine:latest"         # Runtime stage image
  build_script: "scripts/install_certs.sh"

Fields

`base_image`

Custom base image

Default: chosen automatically based on language
Python default: uses AgentKit prebuilt base images and switches automatically according to common.cloud_provider
- volcengine: agentkit-prod-public-cn-beijing.cr.volces.com/base/py-simple:python<version>-bookworm-slim-latest
- byteplus: agentkit-prod-public-ap-southeast-1.cr.bytepluses.com/base/py-simple:python<version>-bookworm-slim-latest
Golang default: agentkit-cn-beijing.cr.volces.com/base/compile_basego:1.24 (build) + agentkit-cn-beijing.cr.volces.com/base/runtime_basego:latest (runtime)

yaml

# Python project - string
base_image: "python:3.12-alpine"

# Go project - mapping (multi-stage build)
base_image:
  builder: "golang:1.24-alpine"
  runtime: "alpine:latest"

`build_script`

Custom build script

Default: none
Purpose: runs a custom script during Docker build
Path: relative to the project root

Typical use cases:

install system dependencies
compile C extensions
download additional resources

yaml

build_script: "scripts/setup.sh"
build_script: "docker/install_deps.sh"

`regenerate_dockerfile`

Force regenerate Dockerfile

Default: false
Purpose: regenerate even if a Dockerfile already exists
CLI flag: --regenerate-dockerfile

`platform`

Target CPU architecture

Default: current system architecture
Purpose: cross-platform builds
CLI flag: --platform

yaml

platform: "linux/amd64"    # x86_64
platform: "linux/arm64"    # ARM (e.g. Apple Silicon)

Global configuration

Global configuration is stored in ~/.agentkit/config.yaml and shared across projects.

Location

~/.agentkit/config.yaml

Example

yaml

# Volcengine credentials
volcengine:
  access_key: "AKLTxxxxxxxx"
  secret_key: "xxxxxxxx"
  region: "cn-beijing"

# Default Container Registry settings
cr:
  instance_name: "my-team-cr-instance"
  namespace_name: "my-team"

# Default TOS settings
tos:
  bucket: "my-team-bucket"
  prefix: "agentkit-builds"
  region: "cn-beijing"

Precedence

When a project config value is empty or set to Auto, AgentKit will automatically fall back to global config:

1. Explicit values in project config (highest)
2. Global config (~/.agentkit/config.yaml)
3. Defaults (lowest)

Typical use cases

Shared team configuration

Teammates can share the same CR instance and TOS bucket:

yaml

# ~/.agentkit/config.yaml
cr:
  instance_name: "team-shared-cr"
  namespace_name: "team-agents"

tos:
  bucket: "team-shared-bucket"

Then in the project config, set the fields to Auto to reuse the team settings:

yaml

# agentkit.yaml
launch_types:
  cloud:
    cr_instance_name: Auto    # Uses team-shared-cr from global config
    tos_bucket: Auto          # Uses team-shared-bucket from global config

Best practices

🌍 Multi-environment management

Create separate config files for different environments:

bash

agentkit.dev.yaml   # Development (local)
agentkit.test.yaml  # Testing (hybrid)
agentkit.prod.yaml  # Production (cloud)

Usage:

bash

# Development
agentkit launch --config-file agentkit.dev.yaml

# Production
agentkit launch --config-file agentkit.prod.yaml

🔐 Secure handling of secrets

❌ Bad practice (hard-coding):

yaml

runtime_envs:
  MODEL_AGENT_API_KEY: c05d49af-1234-5678-abcd-xxxx  # Don't do this!

✅ Recommended approaches:

Option 1: interactive configuration

bash

agentkit config  # Enter sensitive values interactively

Option 2: use .gitignore

bash

# .gitignore
agentkit.local.yaml    # Don't commit local config
agentkit.prod.yaml     # Don't commit prod config
*.secret.yaml          # Any config file containing secrets

Option 3: create a config template

yaml

# agentkit.yaml.template (commit to Git)
runtime_envs:
  MODEL_AGENT_API_KEY: <fill in your API key>
  MODEL_AGENT_NAME: <fill in the endpoint ID>

📝 Add helpful comments

Make config easier for teammates to understand:

yaml

common:
  agent_name: weather_agent
  entry_point: app.py
  launch_type: cloud  # Use cloud deployment for production

launch_types:
  cloud:
    region: cn-beijing  # Beijing region, closest to users
    runtime_envs:
      # Volcano Ark model access credentials
      MODEL_AGENT_API_KEY: xxx
      MODEL_AGENT_NAME: ep-xxx

✅ Validate configuration regularly

Keep your config valid:

bash

# Option 1: run the config command to validate
agentkit config

# Option 2: inspect the config file
cat agentkit.yaml

# Option 3: try building (without deploying)
agentkit build

Full examples

📱 Local development config (Python)

Good for rapid iteration and debugging:

yaml

common:
  agent_name: dev_weather_agent
  entry_point: app.py
  description: Weather query agent for development
  language: Python
  language_version: '3.12'
  launch_type: local
  runtime_envs:
    APP_ENV: development

launch_types:
  local:
    image_tag: dev
    invoke_port: 8000
    runtime_envs:
      MODEL_AGENT_API_KEY: xxx
      DEBUG: 'true'         # Enable debugging
      LOG_LEVEL: debug      # Verbose logs
    ports:
      - "8000:8000"
    memory_limit: 512m      # Lower limits for dev
    cpu_limit: '0.5'

Golang project config

An example configuration for a Go Agent:

yaml

common:
  agent_name: go_agent
  entry_point: main.go
  description: Golang agent
  language: Golang
  language_version: '1.24'
  dependencies_file: go.mod
  launch_type: hybrid

launch_types:
  hybrid:
    region: cn-beijing
    image_tag: "{{timestamp}}"
    cr_instance_name: Auto
    cr_namespace_name: agentkit
    runtime_envs:
      MODEL_AGENT_API_KEY: xxx

docker_build:
  base_image:
    builder: "golang:1.24-alpine"
    runtime: "alpine:latest"

Production config

Suitable for going live:

yaml

common:
  agent_name: prod_weather_agent
  entry_point: server.py
  description: Weather query agent for production
  language: Python
  language_version: '3.12'
  launch_type: cloud
  runtime_envs:
    APP_ENV: production
    LOG_LEVEL: info

launch_types:
  cloud:
    region: cn-beijing
    image_tag: "{{timestamp}}"    # Use a timestamp to ensure uniqueness

    # CR settings
    cr_instance_name: Auto
    cr_namespace_name: production
    cr_repo_name: weather_agent

    # TOS settings
    tos_bucket: Auto

    # Runtime settings
    runtime_name: Auto
    runtime_role_name: Auto
    runtime_apikey_name: Auto

    runtime_envs:
      # Base settings
      MODEL_AGENT_API_KEY: xxx
      MODEL_AGENT_NAME: ep-xxx

      # Observability (recommended in production)
      OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY: xxx
      OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT: http://apmplus-cn-beijing.volces.com:4317
      OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME: prod_weather_agent

docker_build:
  base_image: "python:3.12-slim"

🎯 Minimal configuration examples

Local mode (minimal):

yaml

common:
  agent_name: simple-agent
  entry_point: agent.py
  launch_type: local

Cloud mode (minimal):

yaml

common:
  agent_name: cloud-agent
  entry_point: main.py
  launch_type: cloud

launch_types:
  cloud:
    region: cn-beijing
    runtime_envs:
      MODEL_AGENT_API_KEY: xxx

FAQ

❓ Configuration file not found

Error: Configuration file not found

Fix:

bash

agentkit init my_agent  # Create a new project
# or
agentkit config         # Create config

❓ Invalid YAML format

Error: Invalid YAML format

Checklist:

✅ Use spaces for indentation (do not use tabs)
✅ Ensure there is a space after :
✅ Quote strings containing special characters
✅ Quote template variables: ""

❓ Missing required fields

Error: agent_name is required

Fix:

bash

agentkit config  # Reconfigure and fill required fields

❓ Template variables failed to render

Error: Config field 'cr_instance_name' template variables were not fully rendered

Possible causes:

Volcengine credentials are not configured
Insufficient AK/SK permissions

Fix:

bash

# Check environment variables
echo $VOLC_ACCESSKEY
echo $VOLC_SECRETKEY

# Or check global config
cat ~/.agentkit/config.yaml

❓ Environment variables not taking effect

Possible causes:

Variable name typo
Config was not saved
Not redeployed
Confusing common.runtime_envs with policy-level runtime_envs

Fix:

bash

# 1) Check config
cat agentkit.yaml

# 2) Confirm env var placement
# common.runtime_envs - shared by all modes
# launch_types.<mode>.runtime_envs - specific to the chosen mode

# 3) Redeploy
agentkit deploy

❓ Legacy field names are incompatible

If your config uses legacy field names (for example ve_cr_instance_name or python_version), update them to the new names:

Legacy field	New field
`python_version`	`language_version`
`ve_cr_instance_name`	`cr_instance_name`
`ve_cr_namespace_name`	`cr_namespace_name`
`ve_cr_repo_name`	`cr_repo_name`
`ve_runtime_id`	`runtime_id`
`ve_runtime_name`	`runtime_name`
`ve_runtime_endpoint`	`runtime_endpoint`

💡 Tip: the CLI still supports legacy field names (via aliases), but migration is recommended.

Configuration field quick reference

`common` fields

Field	Required	Default	Description
`agent_name`	✅	-	Agent name
`entry_point`	✅	-	Entry file
`description`	❌	empty	Description
`language`	❌	`Python`	Programming language
`language_version`	❌	`3.12`/`1.24`	Language version
`dependencies_file`	❌	auto-detected	Dependency file
`launch_type`	❌	`local`	Launch type
`runtime_envs`	❌	`{}`	App-level environment variables

Cloud/Hybrid fields

Field	Default	Description
`region`	`cn-beijing`	Volcengine region
`image_tag`		Image tag
`cr_instance_name`	`Auto`	CR instance name
`cr_namespace_name`	`agentkit`	CR namespace
`cr_repo_name`	empty (uses agent_name)	CR repository name
`runtime_name`	`Auto`	Runtime name
`runtime_envs`	`{}`	Policy-level environment variables

`docker_build` fields

Field	Default	Description
`base_image`	auto-selected	Base image
`build_script`	none	Build script
`regenerate_dockerfile`	`false`	Force regenerate
`platform`	current arch	Target platform

Next steps

📖 CLI Overview - learn the main capabilities and concepts
🎮 Commands - learn how each command works
🚀 Quick Start - follow an end-to-end walkthrough

Configuration File Reference ​

Configuration system overview ​

File structure ​

common ​

Example ​

Fields ​

agent_name (required) ​

entry_point (required) ​

description (optional) ​

language (optional) ​

language_version (optional) ​

dependencies_file (optional) ​

launch_type (required) ​

cloud_provider (optional) ​

runtime_envs (optional) ​

Local launch type ​

Example ​

Fields ​

image_tag ​

invoke_port ​

container_name ​

runtime_envs ​

ports ​

volumes ​

restart_policy ​

memory_limit / cpu_limit ​

Auto-managed fields ​

Cloud launch type ​

Example ​

Template variables ​

The Auto keyword ​

Fields ​

region ​

image_tag ​

tos_bucket ​

cr_instance_name ​

cr_namespace_name ​

cr_repo_name ​

runtime_name / runtime_role_name / runtime_apikey_name ​

runtime_envs ​

build_timeout ​

Auto-managed fields ​

Hybrid launch type ​

Example ​

Differences from Cloud mode ​

Fields ​

region ​

image_tag ​

cr_instance_name / cr_namespace_name / cr_repo_name ​

runtime_name / runtime_role_name / runtime_apikey_name ​

runtime_envs ​

Auto-managed fields ​

docker_build ​

Example ​

Fields ​

base_image ​

build_script ​

regenerate_dockerfile ​

platform ​

Global configuration ​

Location ​

Example ​

Precedence ​

Typical use cases ​

Best practices ​

🌍 Multi-environment management ​

🔐 Secure handling of secrets ​

📝 Add helpful comments ​

✅ Validate configuration regularly ​

Full examples ​

📱 Local development config (Python) ​

Golang project config ​

Production config ​

🎯 Minimal configuration examples ​

FAQ ​

❓ Configuration file not found ​

❓ Invalid YAML format ​

❓ Missing required fields ​

❓ Template variables failed to render ​

❓ Environment variables not taking effect ​

Configuration File Reference

Configuration system overview

File structure

`common`

Example

Fields

`agent_name` (required)

`entry_point` (required)

`description` (optional)

`language` (optional)

`language_version` (optional)

`dependencies_file` (optional)

`launch_type` (required)

`cloud_provider` (optional)

`runtime_envs` (optional)

Local launch type

Example

Fields

`image_tag`

`invoke_port`

`container_name`

`runtime_envs`

`ports`

`volumes`

`restart_policy`

`memory_limit` / `cpu_limit`

Auto-managed fields

Cloud launch type

Example

Template variables

The `Auto` keyword

Fields

`region`

`image_tag`

`tos_bucket`

`cr_instance_name`

`cr_namespace_name`

`cr_repo_name`

`runtime_name` / `runtime_role_name` / `runtime_apikey_name`

`runtime_envs`

`build_timeout`

Auto-managed fields

Hybrid launch type

Example

Differences from Cloud mode

Fields

`region`

`image_tag`

`cr_instance_name` / `cr_namespace_name` / `cr_repo_name`

`runtime_name` / `runtime_role_name` / `runtime_apikey_name`

`runtime_envs`

Auto-managed fields

`docker_build`

Example

Fields

`base_image`

`build_script`

`regenerate_dockerfile`

`platform`

Global configuration

Location

Example

Precedence

Typical use cases

Best practices

🌍 Multi-environment management

🔐 Secure handling of secrets

📝 Add helpful comments

✅ Validate configuration regularly

Full examples

📱 Local development config (Python)

Golang project config

Production config

🎯 Minimal configuration examples

FAQ

❓ Configuration file not found

❓ Invalid YAML format

❓ Missing required fields

❓ Template variables failed to render

❓ Environment variables not taking effect