CLI Command Reference

AgentKit CLI is the core tool for interacting with the AgentKit Platform. It provides a complete set of commands designed to simplify and automate the full lifecycle of Agent development, deployment, and management. Whether you are initializing a new project, configuring cloud resources, or testing and iterating on your Agent, AgentKit CLI provides strong support.

This document introduces the purpose, parameters/options, and best practices for each command, helping you use AgentKit CLI efficiently to build excellent Agent applications.

Command Overview

AgentKit CLI follows the standard format: agentkit <command> [arguments] [options].

Command	Description	Core Use Cases
`init`	Initialize a project: Create a brand-new Agent project or wrap existing code.	Start new Agent development; quickly deploy existing code.
`config`	Configure an app: Manage project configuration interactively or non-interactively.	Set deployment mode, environment variables, image tags, etc.
`build`	Build an image: Package your Agent code into a portable Docker image.	Prepare for deployment; CI/CD integration.
`deploy`	Deploy an app: Publish a built image to the target runtime environment.	Go live or update an Agent service.
`launch`	One-command launch: Automatically completes both build and deploy.	Fast iteration; simplified release workflow.
`invoke`	Test invocation: Invoke an Agent locally or in the cloud for functional validation.	Debug Agent logic; end-to-end validation.
`status`	View status: Get runtime status and endpoint information for a deployed Agent.	Monitor service health; obtain access URL.
`destroy`	Clean up resources: Stop and delete deployed Agent instances and related resources.	Take a service offline; release cloud resources.

`agentkit init`

agentkit init guides you through creating a new Agent project. It supports both “start from scratch” and “wrap existing code”, significantly improving bootstrap efficiency.

Modes

Template Mode: Create a project from AgentKit built-in templates. Suitable for developers starting from scratch.
Wrapper Mode: Quickly wrap an existing veadk Agent definition file into a deployable AgentKit project to reuse code.

Syntax

bash

# Template mode: create from a preset template
agentkit init [project_name] [options]

# Wrapper mode: wrap an existing Agent definition file
agentkit init [project_name] --from-agent <path_to_agent_file> [options]

Core Parameter

project_name (optional):
- Description: A unique name for your Agent project, such as smart-faq-agent.
- Default: In template mode, simple_agent; in wrapper mode, auto-generated from the source filename (e.g. agentkit-my_agent).
- Constraints: Can only contain letters, numbers, underscores (_), and hyphens (-).

Template Mode Options

Option	Description	Example
`--template`, `-t`	Select a project template such as `basic`, `basic_stream`, `a2a`.	`--template basic`
`--agent-name`	Set the display name of the Agent.	`--agent-name "Intelligent Customer Support"`
`--description`	Describe what the Agent does (especially important in multi-agent collaboration).	`--description "Handle common user questions"`
`--system-prompt`	Define the Agent system prompt to shape its role and behavior.	`--system-prompt "You are a professional customer support agent..."`
`--model-name`	Specify the model name on Volcengine Ark.	`--model-name "doubao-pro-32k"`
`--tools`	Comma-separated list of tools such as `web_search,run_code`.	`--tools "web_search"`

Wrapper Mode Options

Option	Description	Example
`--from-agent`, `-f`	(Required) Path to an existing Python file that contains a `veadk.Agent` definition.	`--from-agent ./my_existing_agent.py`
`--agent-var`	If auto-detection fails, manually specify the variable name of the Agent object in the file.	`--agent-var "custom_agent_instance"`
`--wrapper-type`	Wrapper type to generate: `basic` (standard) or `stream` (streaming).	`--wrapper-type stream`

Common Options

Option	Description	Default
`--directory`	Target directory where the project will be created.	Current directory (`.`)

Examples

Template Mode

bash

# Example 1: interactive creation; guides you to choose a template
agentkit init my-first-agent

# Example 2: create directly using the 'basic' template
agentkit init weather-report-agent --template basic

# Example 3: create in a specified directory
agentkit init my_agent --template basic_stream --directory ./my_agents

# Example 4: shorthand
agentkit init weather -t basic

# Example 5: customize Agent attributes
agentkit init custom-agent \
  --template basic \
  --agent-name "Advanced Assistant" \
  --description "An agent with web access and code execution" \
  --tools "web_search,run_code"

# Example 6: create a streaming output Agent
agentkit init stream_agent \
  --template basic_stream \
  --agent-name "Streaming Chat Assistant" \
  --model-name "doubao-seed-1-6-250615"

Wrapper Mode

bash

# Example 7: wrap an existing Agent file (auto-detect Agent variable)
agentkit init --from-agent ./my_agent.py

# Example 8: wrap and specify a project name
agentkit init weather_bot --from-agent ./weather_agent.py

# Example 9: shorthand and specify Agent variable name
agentkit init -f ./my_agent.py --agent-var my_custom_agent

# Example 10: generate a streaming wrapper
agentkit init chat_bot \
  --from-agent ./chat_agent.py \
  --wrapper-type stream

# Example 11: wrap into a specified directory
agentkit init deployed_agent \
  --from-agent ../agents/production_agent.py \
  --agent-var prod_agent \
  --wrapper-type basic \
  --directory ./deployment

# Example 12: a complete wrapper command
agentkit init my_deployed_bot \
  -f ~/projects/agents/my_bot.py \
  --agent-var bot \
  --wrapper-type stream \
  --directory ./deploy

Best practices

Start from templates: For new AgentKit users, start with the basic template; it provides a simple project structure.
Leverage wrapper mode: When you already have mature veadk Agent logic, wrapper mode helps you avoid rewriting code and focus on fast deployment.
Use clear names: Give your project and Agent descriptive names to support long-term maintenance and teamwork.

Output

Template mode output

After running a template-mode command, you will see output similar to:

     ✨ Build AI Agents with Ease ✨

Available Templates
┌────┬──────────────────────────┬──────────┬──────────────────────────────────────────────┐
│ ID │ Name                     │ Type     │ Description                                  │
├────┼──────────────────────────┼──────────┼──────────────────────────────────────────────┤
│ 1  │ Basic Agent App          │ Basic App│ Basic Agent app, great for getting started   │
│ 2  │ Basic Stream Agent App   │ Stream App│ Agent app with streaming output             │
│ 3  │ A2A Agent App            │ A2A App  │ Multi-agent app supporting the A2A protocol  │
│ 4  │ Eino A2A Agent App       │ A2A App  │ A2A app based on the Eino framework (Golang) │
└────┴──────────────────────────┴──────────┴──────────────────────────────────────────────┘

Please select a template by entering the ID (1-2):
Template ID: 1
Selected: Basic Agent App

Creating project: my_weather_agent
Using template: Basic Agent App

✨ Project initialized successfully!
Template: Basic Agent App
Entry point: my_weather_agent.py
Language: Python 3.12

Created files:
  ✓ my_weather_agent.py
  ✓ requirements.txt
  ✓ agentkit.yaml
  ✓ .dockerignore

Next steps:
  1. Review and modify the generated files
  2. Use agentkit config to configure your agent
  3. Use agentkit launch to build and deploy

Wrapper mode output 🆕

After running a wrapper-mode command, you will see output similar to:

     ✨ Build AI Agents with Ease ✨

🔄 Wrapping existing Agent file

Project name: agentkit-my_agent
Agent file: ./my_agent.py
Wrapper type: basic

✨ Project initialized successfully!
Template: Agent Wrapper (Basic)
Entry point: agentkit-my_agent.py
Language: Python 3.12
Agent file: my_agent.py
Agent variable: agent

Created files:
  ✓ my_agent.py
  ✓ agentkit-my_agent.py
  ✓ requirements.txt
  ✓ agentkit.yaml
  ✓ .dockerignore

Next steps:
  1. Review and modify the generated files
  2. Use agentkit config to configure your agent
  3. Use agentkit launch to build and deploy

Wrapper mode deep dive 🆕

Wrapper mode is a powerful feature that lets you quickly deploy an existing Agent definition file to the AgentKit platform without rewriting code.

How it works

Parse the Agent file: Automatically analyzes your Python file and identifies the Agent object definition.
Copy the source file: Copies your Agent file into the project directory.
Generate a wrapper: Creates a new Python file that imports and wraps your Agent.
Configure deployment: Generates agentkit.yaml and other required deployment files.

What the wrapper does

The generated wrapper file is responsible for:

Importing your Agent: Imports the Agent object from your file.
Creating a Runner: Wraps the Agent using the veadk Runner.
Providing deployment interfaces: Implements the @app.entrypoint and @app.ping interfaces required by AgentKit.
Handling request/response: Automatically converts HTTP request formats.

Requirements for the Agent file

Your Agent file must meet the following requirements:

Basic requirements:

python

# Must be a Python file (.py)
# Must contain an Agent object definition

from veadk import Agent

# Agent definition - variable name can be agent, my_agent, etc.
agent = Agent(
    model="doubao-seed-1-6-250615",
    description="My Agent"
)

Supported Agent variable names:

The system auto-detects common names such as: agent, main_agent, my_agent, etc.
You can also use a custom name, but you must specify it via --agent-var.

Unsupported cases:

❌ No Agent(...) definition in the file.
❌ Agent definition is inside a function (must be at module level).
❌ Agent object is created via complex logic (must be a direct assignment).

Wrapper type comparison

Feature	Basic wrapper	Stream wrapper
Response mode	Return the full result once	Streaming return (SSE)
Typical scenarios	Standard chat; short responses	Long-form generation; real-time output
Dependencies	`veadk-python`	`veadk-python` + `google-adk`
Config requirements	None	Agent must support streaming output
Client UX	Wait and then show once	Token-by-token display; better interactivity

When to use which

Good scenarios for wrapper mode:

✅ You already have veadk Agent code and want to deploy quickly.
✅ Your Agent is developed and debugged locally and is ready to go live.
✅ Multiple projects share the same Agent definition.
✅ You want to keep Agent code and deployment code separated.

Good scenarios for template mode:

✅ Create a new Agent from scratch.
✅ Learn the AgentKit development workflow.
✅ Need complete example code as a starting point.

Project structure after wrapping

my_project/
├── my_agent.py              # your original Agent definition
├── agentkit-my_agent.py     # wrapper generated by AgentKit (entry point)
├── requirements.txt         # dependencies list (with usage notes)
├── agentkit.yaml            # deployment config (entry_point points to wrapper)
└── .dockerignore            # Docker build ignore rules

Wrapper file example (basic type):

python

# Import your Agent
from my_agent import agent

from veadk import Runner
from agentkit.apps import AgentkitSimpleApp

app = AgentkitSimpleApp()
runner = Runner(agent=agent)


@app.entrypoint
async def run(payload: dict, headers: dict) -> str:
    prompt = payload["prompt"]
    user_id = headers["user_id"]
    session_id = headers["session_id"]

    response = await runner.run(
        messages=prompt,
        user_id=user_id,
        session_id=session_id,
    )
    return response


@app.ping
def ping() -> str:
    return "pong!"


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

FAQ

Q: What if the Agent definition cannot be found?

A: Use --agent-var to explicitly specify the Agent variable name:

bash

agentkit init -f ./my_agent.py --agent-var my_custom_agent_name

Q: Can I modify the generated wrapper?

A: Yes. The wrapper is standard Python code and can be modified as needed. Just make sure @app.entrypoint and @app.ping remain unchanged.

Q: Will the original Agent file be modified?

A: No. The system only copies your file into the target directory; it does not modify the original file.

Q: How do I add extra dependencies in the wrapper project?

A: Edit the generated requirements.txt file and add the dependency packages you need. The file already contains usage notes.

agentkit config

Configure parameters for an Agent application. Three modes are supported: interactive (guided), non-interactive (fast updates), and hybrid (flexible combination).

🆕 Global configuration support: A global configuration file (~/.agentkit/config.yaml) is available to share configuration across projects.

Usage

bash

# Project configuration
agentkit config [arguments] [options]

# Project level: set the cloud provider (volcengine/byteplus)
agentkit config --cloud_provider byteplus

# Global configuration 🆕
agentkit config --global [options]

Three configuration modes

🎯 Interactive mode (default; recommended for first-time setup)

Run with no parameters; the wizard guides you step-by-step:

bash

agentkit config

Interactive flow example:

[1/7] 🤖 Agent name: my_agent
[2/7] 📝 Entry point: my_agent.py  
[3/7] 📄 App description: My weather query agent
[4/7] 🐍 Python version: 3.12
[5/7] 📦 Dependencies file: requirements.txt
[6/7] 🚀 Deployment mode (choose one):
  1. local - build and run locally
  2. hybrid - build locally, run in the cloud
  3. cloud - build and run in the cloud (recommended)
[7/7] 🔐 App-level environment variables (shared by all modes):
  Variable: MODEL_API_KEY=xxxxx

⚡ Non-interactive mode (fast updates; suitable for scripts/CI/CD)

Configure directly via command-line parameters without manual input:

bash

# Full configuration example
agentkit config \
    --agent_name myAgent \
    --entry_point agent.py \
    --launch_type cloud \
    --cloud_provider byteplus \
    --image_tag v1.0.0 \
    --runtime_envs API_KEY=xxxxx

bash

# Incremental updates (only modify part of the configuration)
agentkit config --entry_point new_agent.py
agentkit config --image_tag v1.0.1

🔀 Hybrid mode

Specify some parameters via the command line and input the rest interactively:

bash

agentkit config --agent_name myAgent --interactive

Main parameters

General configuration parameters

Parameter	Description	Example
`--agent_name`	Agent application name	`my_weather_bot`
`--entry_point`	Entry file (must end with `.py`)	`agent.py`
`--description`	App description	`"Weather assistant"`
`--language_version`	Language version	`3.12`
`--dependencies_file`	Dependencies file	`requirements.txt`
`--launch_type`	Deployment mode	`local`, `hybrid`, `cloud`
`--cloud_provider` / `--cloud-provider`	Cloud provider	`volcengine`, `byteplus`

Environment variable configuration (important ⭐)

AgentKit supports two-level environment variable configuration:

Parameter	Level	Description	Use cases
`--runtime_envs` / `-e`	App level	Shared across all deployment modes	API keys, model endpoints, cross-environment configuration
`--workflow-runtime-envs`	Workflow level	Only applies to the current deployment mode	Debug flags, mode-specific configuration

Examples:

bash

# App level (shared across all modes)
agentkit config \
    -e API_KEY=shared-key \
    -e MODEL_ENDPOINT=https://api.example.com

# Workflow level (current mode only)
agentkit config \
    --workflow-runtime-envs DEBUG=true \
    --workflow-runtime-envs LOCAL_CACHE=/tmp

# Mixed usage
agentkit config \
    -e API_KEY=shared \
    --workflow-runtime-envs DEBUG=true

Merge rules:

App-level environment variables are inherited by all workflows.
Workflow-level environment variables only take effect in the current mode.
Variables with the same name: workflow-level overrides app-level.

Cloud/Hybrid mode parameters

Parameter	Description	Example
`--region`	Volcengine region	`cn-beijing`
`--tos_bucket`	TOS bucket	`agentkit-bucket`
`--image_tag`	Image tag	`v1.0.0`, `latest`
`--cr_instance_name`	CR instance name	`my-cr-instance`
`--cr_namespace_name`	CR namespace	`agentkit`
`--cr_repo_name`	CR repository name	`my-agent`

💡 Tip: the --cr_* parameters also support legacy aliases --ve_cr_* for backward compatibility.

Runtime resource bindings (Cloud/Hybrid)

You can use agentkit config to bind (or unbind) runtime resources. When agentkit launch/deploy creates/updates a runtime, the bindings are passed through to the Runtime API.

Supported binding fields:

memory_id: bind a Memory
knowledge_id: bind a Knowledge
tool_id: bind a Tool
mcp_toolset_id: bind an MCP Toolset

Command-line examples:

bash

# Bind resources
agentkit config \
  --memory_id mem-xxx \
  --knowledge_id kb-xxx \
  --tool_id tool-xxx \
  --mcp_toolset_id mcp-ts-xxx

# Unbind (set to empty string)
agentkit config --memory_id ""

YAML persisted location (agentkit.yaml):

yaml

launch_types:
  cloud:  # or hybrid
    runtime_bindings:
      memory_id: mem-xxx
      knowledge_id: kb-xxx
      tool_id: tool-xxx
      mcp_toolset_id: mcp-ts-xxx

💡 Unbind semantics:
Omit a key in config: do not change that binding
Set to "" or null: clear/unbind (a clear operation will be sent when updating the Runtime)

Runtime network configuration (Cloud/Hybrid)

You can use agentkit config to set runtime networking (VPC/private network, public network, or dual-stack). This configuration takes effect only when creating a runtime for the first time (CreateRuntime).

⚠️ Limitation: If a runtime already exists, agentkit launch/deploy will call UpdateRuntime. UpdateRuntime does not support modifying network_configuration, so this setting will not affect existing runtimes. If you need to change the network, destroy and recreate the runtime.

Command-line example (private network):

bash

agentkit config \
  --runtime-network-mode private \
  --runtime-vpc-id vpc-xxxxxxxx \
  --runtime-subnet-id subnet-aaaaaaaa \
  --runtime-enable-shared-internet-access

YAML format (agentkit.yaml):

yaml

launch_types:
  cloud:  # or hybrid
    runtime_network:
      mode: private            # public | private | both
      vpc_id: vpc-xxxxxxxx     # required for private/both
      enable_shared_internet_access: true  # only effective for private/both
      subnet_ids:
        - subnet-aaaaaaaa

mode values:

public: public access only
private: private access only (requires vpc_id)
both: enable both public and private access (requires vpc_id)

enable_shared_internet_access:

Only takes effect when mode is private or both. When enabled, the runtime uses the platform-provided shared public egress to access the public internet.
If mode=public and this flag is enabled, AgentKit will error to prevent a misleading “configured but not effective” setup.

Control options

Option	Description
`--config`, `-c`	Specify the configuration file path (default: `agentkit.yaml`)
`--interactive`, `-i`	Force interactive mode
`--dry-run`	Preview changes without saving
`--show`, `-s`	Show current configuration

Global configuration options 🆕

AgentKit supports a global configuration file (~/.agentkit/config.yaml) for sharing configuration across projects.

Option	Description
`--global`, `-g`	Operate on the global config instead of the project config
`--init`	Initialize the global config file (create a template)
`--set`	Set a global config field (format: `key=value`)

Supported global config fields:

Field	Description	Example
`volcengine.access_key`	Volcengine Access Key	`AK***`
`volcengine.secret_key`	Volcengine Secret Key	`SK***`
`volcengine.region`	Default region	`cn-beijing`
`cr.instance_name`	CR instance name	`team-cr-instance`
`cr.namespace_name`	CR namespace	`agentkit-team`
`tos.bucket`	TOS bucket name	`team-agentkit-builds`
`tos.prefix`	TOS object prefix	`agentkit-builds`
`tos.region`	TOS region	`cn-beijing`

Configuration precedence:

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

Examples

Example 1: first-time configuration (interactive)

bash

agentkit config

Example 2: quickly update a single field

bash

# Update entry point
agentkit config --entry_point new_agent.py

# Update image tag
agentkit config --image_tag v1.0.1

# Add an environment variable
agentkit config -e NEW_KEY=new_value

Example 3: complete non-interactive configuration

bash

agentkit config \
    --agent_name weather-bot \
    --entry_point agent.py \
    --description "Weather assistant" \
    --launch_type cloud \
    --image_tag v1.0.0 \
    --region cn-beijing \
    -e API_KEY=xxxxx \
    -e MODEL_ENDPOINT=https://api.example.com

Example 4: configuration preview (dry run)

bash

# Show changes but do not save
agentkit config --entry_point agent.py --image_tag v2.0 --dry-run

Example output:

General config - changes:
┌──────────────┬──────────────┬──────────────┐
│ Config item   │ Old value     │ New value     │
├──────────────┼──────────────┼──────────────┤
│ entry_point   │ old_agent.py  │ agent.py      │
│ image_tag     │ v1.0          │ v2.0          │
└──────────────┴──────────────┴──────────────┘

🔍 Dry-run: no changes were saved

Example 5: show current configuration

bash

agentkit config --show

Example 6: global configuration management 🆕

Initialize global configuration:

bash

# Create a global config template
agentkit config --global --init

Output:

✅ Global configuration file created: ~/.agentkit/config.yaml

📝 A template has been generated containing the following fields:

🔐 Volcengine credentials
  access_key: ''
  secret_key: ''
  region: cn-beijing

📦 CR configuration
  instance_name: ''
  namespace_name: ''

🗂️  TOS configuration
  bucket: ''
  prefix: agentkit-builds
  region: cn-beijing

Show global configuration:

bash

agentkit config --global --show

Set global configuration:

bash

# Set a single field
agentkit config --global --set cr.instance_name=team-cr-instance
agentkit config --global --set tos.bucket=team-bucket

# Set credentials
agentkit config --global --set volcengine.access_key=AK***
agentkit config --global --set volcengine.secret_key=SK***

Team collaboration scenario:

bash

# 1. Team admin creates and shares global configuration
agentkit config --global --init
vim ~/.agentkit/config.yaml  # fill in team-shared configuration

# 2. Team members automatically use global config when initializing projects
agentkit init my-agent
# related fields in agentkit.yaml are left empty; global config is used at runtime

# 3. Special projects can override global configuration in agentkit.yaml
agentkit config --cr_instance_name special-cr  # override global config

Example 7: CI/CD integration

bash

# Use in CI/CD pipelines
agentkit config \
    --agent_name ${CI_PROJECT_NAME} \
    --entry_point agent.py \
    --launch_type cloud \
    --image_tag ${CI_COMMIT_TAG} \
    -e DEPLOY_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

agentkit launch

Interactive input for environment variables

In interactive mode, environment variable configuration supports convenience commands:

🔐 App-level environment variables (enter KEY=VALUE; empty line to finish)
  
  Available commands:
  - Enter KEY=VALUE to add a variable
  - Enter 'list' to show existing variables
  - Enter 'del KEY' to delete a variable
  - Enter 'clear' to clear all
  - Press Enter on an empty line to finish

Variable: MODEL_API_KEY=xxxxx
✅ Added: MODEL_API_KEY

Variable: list
Current variables:
  MODEL_API_KEY=xxxxx

Variable: [press Enter to finish]
📋 Configured 1 shared variable

Configuration validation

All configuration is validated automatically:

✅ Required fields: Agent name and entry point cannot be empty
✅ Format validation: entry point must end with .py
✅ Option constraints: launch_type must be local, hybrid, or cloud
✅ Naming rules: Agent name can only contain letters, numbers, underscore, hyphen, and dot

Validation failures show detailed errors and exit.

Best practices

Use interactive mode for first-time setup for a guided experience
bash
```
agentkit config
```
Use non-interactive mode for daily updates for speed and efficiency
bash
```
agentkit config --entry_point new_agent.py
```

Use non-interactive mode in CI/CD for full automation

bash

agentkit config --agent_name $PROJECT --image_tag $TAG

Preview before applying to avoid mistakes

bash

agentkit config --entry_point agent.py --dry-run

Manage environment variables by level:
- App level: shared across environments (API keys, etc.)
- Workflow level: mode-specific (debug flags, etc.)

Use global config for team collaboration 🆕:

bash

# Team admin
agentkit config --global --init
agentkit config --global --set cr.instance_name=team-cr
agentkit config --global --set tos.bucket=team-bucket

# Team members
agentkit init my-agent  # automatically uses global config
agentkit launch         # automatically uses global config at runtime

Understand configuration precedence:
- Project config can override global config
- Environment variables have the highest priority
- Order: Environment variables > Project config > Global config > Defaults

agentkit build

Package your Agent code into a Docker image in preparation for deployment.

Usage

bash

agentkit build [options]

Parameter description

--config-file configuration file path

Specify the config file location
Default: agentkit.yaml

--platform build platform

Specify the target platform/architecture
Default: auto (auto-detect)
Usually not needed

--regenerate-dockerfile force regenerate Dockerfile

Force regenerate Dockerfile even if it already exists
Use case: when configuration has changed and you need to refresh the Dockerfile
Default: False

Docker build customization 🛠

AgentKit supports customizing Docker image builds via the docker_build section. Add the following to agentkit.yaml.

Configuration fields

base_image - custom base image

Python projects (string form):

yaml

docker_build:
  base_image: "python:3.12-slim"
  # Or use an Alpine image
  base_image: "python:3.12-alpine"

build_script - custom build script

Path is relative to the project root
Used for installing system dependencies, compiling extensions, etc.
The script runs automatically during the build

yaml

docker_build:
  build_script: "scripts/setup.sh"

Complete example

Python project example:

yaml

agent_name: my-agent
entry_point: agent.py
language: Python
language_version: "3.12"
dependencies_file: requirements.txt
launch_type: local

# Docker build customization
docker_build:
  base_image: "python:3.12-alpine"
  build_script: "scripts/setup.sh"

Build script example (scripts/setup.sh):

bash

#!/bin/bash
# Install system dependencies
apt-get update && apt-get install -y gcc g++ libpq-dev
# Or on Alpine: apk add --no-cache gcc musl-dev postgresql-dev

echo "Custom build script completed"

Use cases

Scenario	Configuration	Example
Use a lightweight image	Specify an Alpine base image	`base_image: "python:3.12-alpine"`
Install system dependencies	Write a build script	`build_script: "scripts/install_deps.sh"`
Compile C extensions	Install a build toolchain	Install gcc, g++, etc. in the script
Configure certificates	Update CA certificates	Run `update-ca-certificates` in the script
Multi-stage builds	Specify builder and runtime separately	Golang projects only

Dockerfile auto-management

Dockerfile is auto-generated based on configuration and includes a metadata header
Automatically updated when configuration changes (old versions are backed up to .agentkit/dockerfile_backups/)
If you remove the metadata header, AgentKit will no longer manage the file automatically
Use --regenerate-dockerfile to force regeneration

Example metadata header:

dockerfile

# ============================================================================
# AUTO-GENERATED by AgentKit v1.x.x
# ============================================================================
# Source: agentkit.yaml
# Checksum: sha256:...
# Generated: 2025-01-17T10:30:00
# 
# This file is automatically generated and managed by AgentKit:
#   - It will be auto-updated when agentkit.yaml config changes
#   - To fully customize, remove this header comment
# ============================================================================

Build process

The build strategy is chosen automatically based on launch_type:

🏠 Local mode (build locally)

Build with Docker on your machine:

🔨 Starting local image build...
[1/3] Generating Dockerfile...
[2/3] Building Docker image...
[3/3] Verifying image availability...
✅ Build succeeded: my-agent:latest

Estimated time: 1–3 minutes.

☁️ Cloud mode (build in the cloud)

Build automatically on Volcengine:

🔨 Starting cloud build...
[1/6] Generating Dockerfile...
[2/6] Packaging project code...
[3/6] Uploading to object storage...
[4/6] Preparing image registry...
[5/6] Creating build pipeline...
[6/6] Executing build task...
✅ Build succeeded: xxx.cr.volces.com/agentkit/my-agent:latest

Estimated time: 3–5 minutes.

Build result

Image name: {agent_name}:{image_tag}
Image information: automatically saved into the configuration file
Build record: includes timestamp, image ID, etc.

Examples

bash

# Example 1: build with default configuration
agentkit build

# Example 2: specify config file
agentkit build --config-file ./prod.yaml

# Example 3: force regenerate Dockerfile
agentkit build --regenerate-dockerfile

# Example 4: force refresh after config changes
agentkit build --config-file ./prod.yaml --regenerate-dockerfile

Custom build examples

Example 5: use an Alpine base image

Modify agentkit.yaml:

yaml

docker_build:
  base_image: "python:3.12-alpine"
  build_script: "scripts/alpine-setup.sh"

Create scripts/alpine-setup.sh:

bash

#!/bin/sh
apk add --no-cache gcc musl-dev postgresql-dev

Build:

bash

agentkit build

Example 6: install system dependencies (C extensions)

Modify agentkit.yaml:

yaml

docker_build:
  build_script: "scripts/install-deps.sh"

Create scripts/install-deps.sh:

bash

#!/bin/bash
apt-get update && apt-get install -y \
    gcc g++ \
    libpq-dev \
    libxml2-dev \
    libxslt1-dev

Build:

bash

agentkit build

Example 7: Golang multi-stage build

Modify agentkit.yaml:

yaml

docker_build:
  base_image:
    builder: "golang:1.24-alpine"
    runtime: "alpine:3.19"
  build_script: "scripts/install-certs.sh"

Build:

bash

agentkit build

Notes

Local mode prerequisites:

✅ Ensure Docker is installed and running
✅ Docker daemon is accessible

Cloud mode prerequisites:

✅ Set AK/SK credentials
✅ Ensure network access to Volcengine

Docker build customization:

✅ Build script path should be relative to the project root
✅ Scripts automatically gain execute permissions
✅ Missing build scripts produce warnings but do not stop the build
✅ Dockerfile is auto-generated and updated when configuration changes
✅ Older Dockerfiles are backed up to .agentkit/dockerfile_backups/
✅ Removing the metadata header disables automatic management

Tip: build metadata will be written back to the config file for use by the deploy command.

agentkit deploy

Deploy the built image and start the Agent to serve requests.

Usage

bash

agentkit deploy [options]

Parameter Description

--config-file Configuration file path

Specify the config file location
Default: agentkit.yaml

Deployment Process

Automatically selects the deployment target based on the configured launch_type:

🏠 Local Mode (Local Deployment)

Starts the container on your local machine:

🚀 Starting deployment to local Docker...
[1/3] Stopping old container version...
[2/3] Starting new container...
[3/3] Verifying container status...
✅ Deployment successful! Container is running
🌐 Access URL: http://localhost:8000

Estimated time: 10-30 seconds

☁️ Cloud Mode (Cloud Deployment)

Creates a Runtime on Volcengine:

🚀 Starting deployment to cloud platform...
✅ Generated Runtime name: my-agent-20250120-abc123
✅ Created Runtime: r-xxxxxx
⏳ Waiting for Runtime to be ready...
✅ Runtime is ready!
🌐 Access URL: http://xxx.apigateway-cn-beijing.volceapi.com

Estimated time: 1-2 minutes

Usage Examples

bash

# Example 1: Deploy to default environment
agentkit deploy

# Example 2: Deploy to production environment
agentkit deploy --config-file ./prod.yaml

After Deployment

Local Mode:

✅ Container running locally
✅ Accessible via localhost:port
✅ Automatic health checks

Cloud Mode:

✅ Runtime running in the cloud
✅ Get a publicly accessible URL
✅ Automatic Runtime status verification

agentkit launch

Build + Deploy in one step! Equivalent to automatically running build then deploy.

Usage

bash

agentkit launch [options]

Parameter Description

--config-file Configuration file path

Specify the config file location
Default: agentkit.yaml

Execution Flow

🚀 Starting Agent launch...

━━━ Step 1: Build Image ━━━
🔨 Reading config: agentkit.yaml
🔨 Starting build...
✅ Build completed

━━━ Step 2: Deploy Application ━━━
🚀 Starting deployment...
✅ Deployment completed

✨ Agent launched successfully!

Usage Examples

bash

# Example 1: One-click launch
agentkit launch

# Example 2: Launch to production environment
agentkit launch --config-file ./prod.yaml

Why Use launch

⚡ Time-saving - One command instead of two
🔒 Version consistency - Ensures build and deploy use the same configuration
🚀 Fast iteration - Test immediately after code changes

agentkit invoke

Send a test request to a deployed Agent to verify functionality.

Usage

bash

agentkit invoke [message content] [options]

⚠️ Important: You must provide either message content or the --payload option, but not both

Parameter Description

Message Content

Enter the text you want to send directly after the command, without any option flags
Will be automatically wrapped as {"prompt": "your message"}
Cannot be used with --payload
Example: agentkit invoke "hello" or agentkit invoke "how's the weather today?"

Options

--payload, -p Custom request data

Specify complete request content in JSON format
Cannot be used with message content
Example: --payload '{"prompt": "hello", "context": "greeting"}'

--headers, -h Custom request headers

Specify HTTP headers in JSON format
Automatically adds user_id and session_id by default
Example: --headers '{"user_id": "test123"}'

--raw Output raw response (for debugging)

For streaming calls: prints SSE event JSON from server line by line to verify event format
For non-streaming calls: outputs compact raw JSON (no pretty indent)
Example: agentkit invoke "hello" --raw

--show-reasoning Output reasoning content (for LangChain debugging)

When streaming events contain additional_kwargs.reasoning_content, incrementally prints this field
Displayed separately from final answer (Reasoning first, then Answer)
Example: agentkit invoke "1+1=?" --show-reasoning

--apikey, -ak API Key

May be required for cloud deployment (Cloud mode)
Used for authentication
Optional parameter

--config-file Configuration file path

Specify the config file location
Default: agentkit.yaml in current directory

Usage Examples

Example 1: Send message directly (simplest)

bash

agentkit invoke "How's the weather in Hangzhou today?"

Equivalent to sending the following JSON:

json

{
  "prompt": "How's the weather in Hangzhou today?"
}

Example 2: Custom request content

bash

agentkit invoke --payload '{"prompt": "Hangzhou weather?", "user_location": "Hangzhou"}'

Example 3: With headers

bash

agentkit invoke \
  --payload '{"prompt": "Hangzhou weather?"}' \
  --headers '{"user_id": "user123", "session_id": "sess456"}'

Example 4: Cloud deployment (with API Key)

bash

agentkit invoke "hello" --apikey your_api_key_here

Execution Output

💬 Calling Agent...
✅ Runtime ID: r-xxxxxx
🌐 Calling address: http://xxx.apigateway-cn-beijing.volceapi.com
✅ Call successful!

📡 Agent response:
Hangzhou is sunny today, 22°C, great for going out.

Notes

⚠️ Message content and --payload are mutually exclusive
⚠️ Cloud deployment may require API Key
⚠️ Ensure Agent is deployed before calling (check with agentkit status)

agentkit status

View the Agent's running status, including whether it's online, access URL, and other information.

Usage

bash

agentkit status [options]

Parameter Description

--config-file Configuration file path

Specify the config file location
Default: agentkit.yaml

Output Example

🏠 Local Mode

✅ Container name: my-agent
✅ Running status: running
🌐 Access URL: http://localhost:8000

Details:
{
    "container_id": "abc123...",
    "status": "running",
    "ports": ["8000:8000"],
    "created": "2025-01-20 10:00:00",
    "health": "healthy"
}

☁️ Cloud Mode

✅ Runtime ID: r-xxxxxx
✅ Running status: Ready
🌐 Access URL: http://xxx.apigateway-cn-beijing.volceapi.com

Details:
{
    "runtime_id": "r-xxxxxx",
    "runtime_name": "my-agent-20250120-abc123",
    "status": "Ready",
    "endpoint": "http://xxx.apigateway-cn-beijing.volceapi.com",
    "image": "xxx.cr.volces.com/agentkit/my-agent:latest",
    "created_at": "2025-01-20 10:00:00"
}

Status Description

Local Mode Status:

✅ running - Running normally
⏸️ stopped - Stopped
🔄 restarting - Restarting
❌ error - Error occurred

Cloud Mode Status:

✅ Ready - Ready to receive requests
🔄 Releasing - Deploying
❌ Error - Runtime error
❌ Failed - Deployment failed

Usage Examples

bash

# Example 1: View current status
agentkit status

# Example 2: View production environment status
agentkit status --config-file ./prod.yaml

agentkit destroy

Stop and delete the Agent instance, releasing resources. ⚠️ This operation is irreversible!

Usage

bash

agentkit destroy [options]

Parameter Description

--force Force delete

Skip confirmation prompt and delete directly
Default is off (will ask for confirmation)
Use with caution!

--config-file Configuration file path

Specify the config file location
Default: agentkit.yaml

Safety Confirmation

By default, you will be asked to confirm the operation:

🗑️ Preparing to destroy running Agent...
⚠️ This operation cannot be undone!
Are you sure you want to continue? [y/N]: y

Skip confirmation (not recommended):

bash

agentkit destroy --force

What Will Be Deleted

🏠 Local Mode

✅ Stop Docker container
✅ Delete container instance
⚠️ Image will be retained (can be manually deleted)

☁️ Cloud Mode

✅ Delete Runtime instance
✅ Release cloud resources
⚠️ Image will be retained (can be manually deleted in CR)

Execution Output

🗑️ Starting to destroy Agent resources...
✅ Stopped Runtime: r-xxxxxx
✅ Runtime deleted successfully
✅ Resources cleaned up

Tip: Configuration file and images are retained, can redeploy anytime.

Usage Examples

bash

# Example 1: Safe deletion (recommended)
agentkit destroy

# Example 2: Force deletion
agentkit destroy --force

# Example 3: Delete specified environment
agentkit destroy --config-file ./dev.yaml

Important Notes

⚠️ Irreversible: Cannot be undone after deletion, data will be permanently lost
✅ Config retained: agentkit.yaml file will not be deleted
✅ Image retained: Docker images will not be deleted, can redeploy
💡 Redeploy: Can redeploy anytime with agentkit deploy

Common Options

All commands support these options:

--help View Help

View detailed descriptions and parameters for any command:

bash

# View help for a specific command
agentkit invoke --help
agentkit build --help

# View list of all commands
agentkit --help

--version View Version

Display CLI version information:

bash

agentkit --version
# or
agentkit -v

Platform Service Commands

AgentKit CLI provides rich platform service management commands for managing Memory, Knowledge, Tools, and Runtime resources.

`agentkit memory`

Manage AgentKit Memory collections, supporting create, view, update, and delete operations.

bash

# Create memory collection (default provider-type: MEM0)
agentkit memory create --name my-memory --description "My memory collection"

# Add external memory collection
agentkit memory add --provider-collection-id <id> --provider-type VIKINGDB_MEMORY --name my-external-memory

# List all memory collections (supports pagination and filtering)
agentkit memory list
agentkit memory list --name-contains "my" --limit 10

# View memory collection details
agentkit memory show -m <id>

# Update memory collection
agentkit memory update -m <id> --description "Updated description"

# Delete memory collection
agentkit memory delete -m <id>

# Get connection information
agentkit memory conn -m <id>

# View supported Provider types
agentkit memory provider-types

`agentkit knowledge`

Manage AgentKit Knowledge bases, supporting CRUD operations.

bash

# Add knowledge base (connect external knowledge base)
agentkit knowledge add --name my-kb --provider-knowledge-id <id> --provider-type VIKINGDB_KNOWLEDGE

# List all knowledge bases (supports pagination and filtering)
agentkit knowledge list
agentkit knowledge list --status Ready

# View knowledge base details
agentkit knowledge show -k <id>

# Update knowledge base
agentkit knowledge update -k <id> --description "Updated description"

# Delete knowledge base
agentkit knowledge delete -k <id>

# Get connection information
agentkit knowledge conn -k <id>

# View supported Provider types
agentkit knowledge provider-types

`agentkit tools`

Manage AgentKit Tools and Sessions, including tool lifecycle management and session operations.

bash

# Tool management
# Create tool (needs to specify tool-type)
agentkit tools create --name my-tool --tool-type <type> --description "My tool"
# List tools (supports pagination and filtering)
agentkit tools list
# View tool details
agentkit tools show -t <id>
# Update tool
agentkit tools update -t <id> --description "New description"
# Delete tool
agentkit tools delete -t <id>

# Session management
# Create session
agentkit tools session create -t <id> --name my-session --ttl 30 --ttl-unit minute
# List sessions
agentkit tools session list -t <id>
# View session details
agentkit tools session show -t <id> -s <session_id>
# Get session logs
agentkit tools session logs -t <id> -s <session_id>
# Set session TTL
agentkit tools session set-ttl -t <id> -s <session_id> --ttl 60 --ttl-unit minute
# Delete session
agentkit tools session delete -t <id> -s <session_id>

`agentkit runtime`

Manage AgentKit Runtime instances, supporting runtime create, update, delete, and version management.

bash

# Create runtime (needs to specify artifact info)
agentkit runtime create \
  --name my-runtime \
  --role-name <role> \
  --artifact-type DockerImage \
  --artifact-url <url> \
  --description "My runtime"

# Create runtime and associate resources
agentkit runtime create \
  --name my-runtime \
  --role-name <role> \
  --artifact-type DockerImage \
  --artifact-url <url> \
  --memory-id mem-xxx \
  --knowledge-id kb-xxx \
  --tool-id tool-xxx \
  --mcp-toolset-id mcp-ts-xxx

# Create runtime with private network access (VPC)
agentkit runtime create \
  --name my-runtime \
  --role-name <role> \
  --artifact-type DockerImage \
  --artifact-url <url> \
  --vpc-id vpc-xxxxxxxx \
  --subnet-ids subnet-aaaaaaaa \
  --enable-private-network \
  --enable-public-network false

# List all runtimes (supports pagination and filtering)
agentkit runtime list

# View runtime details
agentkit runtime get -r <id>

# Update runtime
agentkit runtime update -r <id> --description "New description"

> 💡 Tip: `agentkit runtime update` currently only supports updating artifact/description/env/tags and resource binding fields (`memory-id/knowledge-id/tool-id/mcp-toolset-id`), network configuration cannot be modified.

# Delete runtime
agentkit runtime delete -r <id>

# Release new version
agentkit runtime release -r <id> --version-number <version>

# View specific version details
agentkit runtime version -r <id> --version-number <version>

# List all versions
agentkit runtime versions -r <id>

Common Workflows

📝 Complete Development Workflow (Template Mode)

Complete steps from zero to production:

bash

# 1️⃣ Create project
agentkit init weather_agent --template basic
cd weather_agent

# 2️⃣ Configure app
agentkit config

# 3️⃣ One-click deploy
agentkit launch

# 4️⃣ Test functionality
agentkit invoke "How's the weather in Hangzhou?"

# 5️⃣ Check status
agentkit status

🔄 Quick Deploy Existing Agent (Wrapper Mode) 🆕

Quickly deploy an existing Agent:

bash

# 1️⃣ Wrap existing Agent file
agentkit init --from-agent ~/my_projects/weather_agent.py

# 2️⃣ Enter project directory
cd agentkit-weather_agent

# 3️⃣ (Optional) Configure app
agentkit config

# 4️⃣ One-click deploy
agentkit launch

# 5️⃣ Test functionality
agentkit invoke "How's the weather today?"

# 6️⃣ Check status
agentkit status

🔄 Quick Iteration Workflow

Update workflow after code changes:

bash

# Method 1: Step-by-step (recommended for debugging)
agentkit build        # Rebuild
agentkit deploy       # Redeploy
agentkit invoke "test"  # Test validation

# Method 2: One-click update (recommended for daily development)
agentkit launch       # Auto build+deploy
agentkit invoke "test"  # Test validation

🌍 Multi-Environment Management

Switch between dev, test, and production environments:

bash

# Development environment
agentkit launch --config-file agentkit.dev.yaml
agentkit invoke "test" --config-file agentkit.dev.yaml

# Production environment
agentkit launch --config-file agentkit.prod.yaml
agentkit invoke "test" --config-file agentkit.prod.yaml

FAQ

Don't panic when you encounter errors, here are solutions!

❌ Configuration file not found

Error: Configuration file not found: agentkit.yaml

Cause: No configuration file in current directory

Solution:

bash

# If new project
agentkit init my_agent

# If existing project
agentkit config

❌ Docker not running (Local Mode)

Error: Docker daemon not running

Cause: Docker service not started

Solution:

Windows/Mac: Open Docker Desktop
Linux: sudo systemctl start docker

❌ Cloud credentials not configured (Cloud Mode)

Error: VOLC_ACCESSKEY or VOLC_SECRETKEY not set

Cause: Volcengine AK/SK not set

Solution:

bash

# Recommended: Use secure global config
agentkit config --global --init
agentkit config --global --set volcengine.access_key="your AccessKey"
agentkit config --global --set volcengine.secret_key="your SecretKey"

# Or: Temporary environment variables (for dev/debugging)
export VOLC_ACCESSKEY="your AccessKey"
export VOLC_SECRETKEY="your SecretKey"

❌ Build failed

❌ Build failed: ...

Possible causes and solutions:

Dependency issues - Check if requirements.txt is correct
Code errors - Check if Python code has syntax errors
Network issues - Check network connection, retry build
Permission issues - Ensure you have Docker/cloud operation permissions

💡 Debugging Tips

1. View detailed logs

bash

# Set verbose log level
export LOG_LEVEL=DEBUG
agentkit build

2. Verify configuration file

bash

# Check if configuration is correct
cat agentkit.yaml

3. Execute step by step

bash

# Execute separately, easier to locate issues
agentkit build    # Build first
agentkit deploy   # Then deploy
# Instead of using launch directly

4. Check running status

bash

# Check if Agent is running normally
agentkit status

Next Steps

📖 Configuration Guide - Deep dive into each configuration item
🚀 Quick Start - Follow the tutorial to practice
❓ Troubleshooting - More troubleshooting solutions

CLI Command Reference ​

Command Overview ​

agentkit init ​

Modes ​

Syntax ​

Core Parameter ​

Template Mode Options ​

Wrapper Mode Options ​

Common Options ​

Examples ​

Template Mode ​

Wrapper Mode ​

Output ​

Template mode output ​

Wrapper mode output 🆕 ​

Wrapper mode deep dive 🆕 ​

How it works ​

What the wrapper does ​

Requirements for the Agent file ​

Wrapper type comparison ​

When to use which ​

Project structure after wrapping ​

FAQ ​

agentkit config ​

Usage ​

Three configuration modes ​

🎯 Interactive mode (default; recommended for first-time setup) ​

⚡ Non-interactive mode (fast updates; suitable for scripts/CI/CD) ​

🔀 Hybrid mode ​

Main parameters ​

General configuration parameters ​

Environment variable configuration (important ⭐) ​

Cloud/Hybrid mode parameters ​

Runtime resource bindings (Cloud/Hybrid) ​

Runtime network configuration (Cloud/Hybrid) ​

Control options ​

Global configuration options 🆕 ​

Examples ​

Example 1: first-time configuration (interactive) ​

Example 2: quickly update a single field ​

Example 3: complete non-interactive configuration ​

Example 4: configuration preview (dry run) ​

Example 5: show current configuration ​

Example 6: global configuration management 🆕 ​

Example 7: CI/CD integration ​

Interactive input for environment variables ​

Configuration validation ​

Best practices ​

agentkit build ​

Usage ​

Parameter description ​

Docker build customization 🛠 ​

Configuration fields ​

Complete example ​

Use cases ​

Dockerfile auto-management ​

Build process ​

🏠 Local mode (build locally) ​

☁️ Cloud mode (build in the cloud) ​

Build result ​

Examples ​

Custom build examples ​

Notes ​

agentkit deploy ​

Usage ​

Parameter Description ​

Deployment Process ​

🏠 Local Mode (Local Deployment) ​

☁️ Cloud Mode (Cloud Deployment) ​

Usage Examples ​

After Deployment ​

agentkit launch ​

Usage ​

Parameter Description ​

Execution Flow ​

Usage Examples ​

Why Use launch ​

agentkit invoke ​

Usage ​

Parameter Description ​

CLI Command Reference

Command Overview

`agentkit init`

Modes

Syntax

Core Parameter

Template Mode Options

Wrapper Mode Options

Common Options

Examples

Template Mode

Wrapper Mode

Output

Template mode output

Wrapper mode output 🆕

Wrapper mode deep dive 🆕

How it works

What the wrapper does

Requirements for the Agent file

Wrapper type comparison

When to use which

Project structure after wrapping

FAQ

agentkit config

Usage

Three configuration modes

🎯 Interactive mode (default; recommended for first-time setup)

⚡ Non-interactive mode (fast updates; suitable for scripts/CI/CD)

🔀 Hybrid mode

Main parameters

General configuration parameters

Environment variable configuration (important ⭐)

Cloud/Hybrid mode parameters

Runtime resource bindings (Cloud/Hybrid)

Runtime network configuration (Cloud/Hybrid)

Control options

Global configuration options 🆕

Examples

Example 1: first-time configuration (interactive)

Example 2: quickly update a single field

Example 3: complete non-interactive configuration

Example 4: configuration preview (dry run)

Example 5: show current configuration

Example 6: global configuration management 🆕

Example 7: CI/CD integration

Interactive input for environment variables

Configuration validation

Best practices

agentkit build

Usage

Parameter description

Docker build customization 🛠

Configuration fields

Complete example

Use cases

Dockerfile auto-management

Build process

🏠 Local mode (build locally)

☁️ Cloud mode (build in the cloud)

Build result

Examples

Custom build examples

Notes

agentkit deploy

Usage

Parameter Description

Deployment Process

🏠 Local Mode (Local Deployment)

☁️ Cloud Mode (Cloud Deployment)

Usage Examples

After Deployment

agentkit launch

Usage

Parameter Description

Execution Flow

Usage Examples

Why Use launch

agentkit invoke

Usage

Parameter Description