CLI 命令详解

AgentKit CLI 是您与 AgentKit Platform 交互的核心工具，提供了一套完整的命令集，旨在简化和自动化 Agent 开发、部署和管理的整个生命周期。无论您是初始化新项目、配置云端资源，还是测试和迭代您的 Agent，AgentKit CLI 都能提供强大支持。

本篇文档将详细介绍每个命令的功能、参数选项和最佳实践，帮助您高效利用 AgentKit CLI 构建卓越的 Agent 应用。

命令总览

AgentKit CLI 遵循标准的 agentkit <command> [arguments] [options] 格式。

命令	功能描述	核心应用场景
`init`	初始化项目：创建全新的 Agent 项目或包装现有代码。	启动新 Agent 开发、快速部署已有代码。
`config`	配置应用：以交互或非交互方式管理项目配置。	设置部署模式、环境变量、镜像标签等。
`build`	构建镜像：将您的 Agent 代码打包成可移植的 Docker 镜像。	准备部署、CI/CD 集成。
`deploy`	部署应用：将已构建的镜像发布到目标运行环境。	上线或更新 Agent 服务。
`launch`	一键启动：自动完成构建和部署两个步骤。	快速迭代、简化上线流程。
`invoke`	测试调用：在本地或云端直接调用 Agent，进行功能验证。	调试 Agent 逻辑、验证端到端功能。
`status`	查看状态：获取已部署 Agent 的运行状态和端点信息。	监控服务健康状况、获取访问地址。
`destroy`	清理资源：停止并删除已部署的 Agent 实例及相关资源。	下线服务、释放云资源。

`agentkit init`

agentkit init 命令用于引导一个新的 Agent 项目，支持从零开始和基于现有代码两种模式，极大提升了项目启动效率。

使用模式

模板模式 (Template Mode)：从 AgentKit 提供的内置模板创建项目，适合从零开始的开发者。
包装模式 (Wrapper Mode)：将您已有的 veadk Agent 定义文件快速包装成可部署的 AgentKit 项目，实现代码复用。

命令格式

bash

# 模板模式：从预设模板创建
agentkit init [project_name] [options]

# 包装模式：包装现有的 Agent 定义文件
agentkit init [project_name] --from-agent <path_to_agent_file> [options]

核心参数

project_name (可选):
- 描述：为您的 Agent 项目指定一个唯一的名称，如 smart-faq-agent。
- 默认值：模板模式下为 simple_agent；包装模式下根据源文件名自动生成 (例如 agentkit-my_agent)。
- 约束：只能包含字母、数字、下划线 (_) 和中划线 (-)。

模板模式选项

选项	描述	示例
`--template`, `-t`	选择项目模板，如 `basic` 或 `basic_stream`。	`--template basic`
`--agent-name`	设置 Agent 的显示名称。	`--agent-name "智能客服"`
`--description`	Agent 的功能描述，在多 Agent 协作场景中尤为重要。	`--description "处理常见的用户问题"`
`--system-prompt`	定义 Agent 的系统提示词，塑造其角色和行为。	`--system-prompt "你是一个专业的客服..."`
`--model-name`	指定火山引擎方舟平台上的模型名称。	`--model-name "doubao-pro-32k"`
`--tools`	以逗号分隔的工具列表，如 `web_search,run_code`。	`--tools "web_search"`

包装模式选项

选项	描述	示例
`--from-agent`, `-f`	(必需) 指定包含 `veadk.Agent` 定义的现有 Python 文件路径。	`--from-agent ./my_existing_agent.py`
`--agent-var`	当自动检测失败时，手动指定 Agent 对象在文件中的变量名。	`--agent-var "custom_agent_instance"`
`--wrapper-type`	生成的包装器类型，`basic` (标准) 或 `stream` (流式)。	`--wrapper-type stream`

通用选项

选项	描述	默认值
`--directory`	指定创建项目的目标目录。	当前目录 (`.`)

使用示例

模板模式

bash

# 示例 1: 交互式创建，引导您选择模板
agentkit init my-first-agent

# 示例 2: 直接使用 'basic' 模板创建
agentkit init weather-report-agent --template basic

# 示例 3：在指定目录创建
agentkit init my_agent --template basic_stream --directory ./my_agents

# 示例 4：使用简写
agentkit init weather -t basic

# 示例 5: 自定义 Agent 属性
agentkit init custom-agent \
  --template basic \
  --agent-name "高级助理" \
  --description "一个具备联网和代码执行能力的 Agent" \
  --tools "web_search,run_code"

# 示例 6：创建流式输出的 Agent
agentkit init stream_agent \
  --template basic_stream \
  --agent-name "流式对话助手" \
  --model-name "doubao-seed-1-6-250615"

包装模式

bash

# 示例 7：包装现有 Agent 文件（自动检测 Agent 变量）
agentkit init --from-agent ./my_agent.py

# 示例 8：包装并指定项目名称
agentkit init weather_bot --from-agent ./weather_agent.py

# 示例 9：使用简写和指定 Agent 变量名
agentkit init -f ./my_agent.py --agent-var my_custom_agent

# 示例 10：生成流式输出包装器
agentkit init chat_bot \
  --from-agent ./chat_agent.py \
  --wrapper-type stream

# 示例 11：在指定目录包装
agentkit init deployed_agent \
  --from-agent ../agents/production_agent.py \
  --agent-var prod_agent \
  --wrapper-type basic \
  --directory ./deployment

# 示例 12：完整的包装命令
agentkit init my_deployed_bot \
  -f ~/projects/agents/my_bot.py \
  --agent-var bot \
  --wrapper-type stream \
  --directory ./deploy

最佳实践

从模板开始：如果您是 AgentKit 新手，强烈建议从 basic 模板开始，它提供了最简洁的项目结构。
利用包装模式：当您已经拥有成熟的 veadk Agent 逻辑时，使用包装模式可以避免重写代码，专注于快速部署。
明确命名：为您的项目和 Agent 取一个描述性的名称，有助于长期维护和团队协作。

运行效果

模板模式输出

当你运行模板模式命令后，会看到类似这样的输出：

     ✨ Build AI Agents with Ease ✨

Available Templates
┌────┬──────────────────────────┬──────────┬──────────────────────────────────┐
│ ID │ Name                     │ Type     │ Description                      │
├────┼──────────────────────────┼──────────┼──────────────────────────────────┤
│ 1  │ Basic Agent App          │ Basic App│ 最简单的Agent应用，快速上手        │
│ 2  │ Basic Stream Agent App   │ Stream App│ 支持流式输出的Agent应用           │
└────┴──────────────────────────┴──────────┴──────────────────────────────────┘

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

包装模式输出 🆕

当你运行包装模式命令后，会看到类似这样的输出：

     ✨ 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

包装模式详解 🆕

包装模式是一个强大的功能，让你能够快速将已有的 Agent 定义文件部署到 AgentKit 平台，无需重写代码。

工作原理

解析 Agent 文件：自动分析你的 Python 文件，识别 Agent 对象定义
复制源文件：将你的 Agent 文件复制到项目目录
生成包装器：创建一个新的 Python 文件，导入并包装你的 Agent
配置部署：生成 agentkit.yaml 和其他必要的部署文件

包装器的作用

生成的包装器文件负责：

导入你的 Agent：从你的文件中导入 Agent 对象
创建 Runner：使用 veadk 的 Runner 包装 Agent
提供部署接口：实现 AgentKit 要求的 @app.entrypoint 和 @app.ping 接口
处理请求/响应：自动处理 HTTP 请求格式转换

Agent 文件要求

你的 Agent 文件需要满足以下条件：

基本要求：

python

# 必须是 Python 文件 (.py)
# 必须包含 Agent 对象定义

from veadk import Agent

# Agent 定义 - 变量名可以是 agent、my_agent 等
agent = Agent(
    model="doubao-seed-1-6-250615",
    description="我的 Agent"
)

支持的 Agent 变量名：

系统会自动检测常见命名：agent, main_agent, my_agent 等
也可以使用自定义命名，但需要用 --agent-var 参数指定

不支持的情况：

❌ 文件中没有 Agent(...) 定义
❌ Agent 定义在函数内部（必须在模块级别）
❌ Agent 对象通过复杂的逻辑生成（需要直接赋值）

包装器类型对比

特性	Basic 包装器	Stream 包装器
响应方式	一次性返回完整结果	流式返回（SSE）
适用场景	标准对话、短响应	长文本生成、实时输出
依赖包	`veadk-python`	`veadk-python` + `google-adk`
配置要求	无特殊要求	Agent 需要支持流式输出
客户端体验	等待后一次性显示	逐字显示，更好的交互体验

使用场景

适合使用包装模式的场景：

✅ 已有 veadk Agent 代码，想快速部署
✅ 在本地开发调试好的 Agent，准备上线
✅ 多个项目共享同一个 Agent 定义
✅ 想要保持 Agent 代码和部署代码分离

适合使用模板模式的场景：

✅ 从零开始创建新 Agent
✅ 学习 AgentKit 开发流程
✅ 需要完整的示例代码作为起点

包装后的项目结构

my_project/
├── my_agent.py              # 你的原始 Agent 定义
├── agentkit-my_agent.py     # AgentKit 生成的包装器（入口文件）
├── requirements.txt         # 依赖列表（含使用提示）
├── agentkit.yaml           # 部署配置（entry_point 指向包装器）
└── .dockerignore           # Docker 构建忽略规则

包装器文件示例 (basic 类型)：

python

# 导入你的 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)

常见问题

Q: 找不到 Agent 定义怎么办？

A: 使用 --agent-var 参数明确指定 Agent 变量名：

bash

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

Q: 可以修改生成的包装器吗？

A: 可以！包装器是标准的 Python 代码，你可以根据需要自由修改。但要注意保持 @app.entrypoint 和 @app.ping 接口不变。

Q: 原始 Agent 文件会被修改吗？

A: 不会！系统只会复制你的文件到目标目录，不会修改原文件。

Q: 如何在包装器中添加额外的依赖？

A: 编辑生成的 requirements.txt 文件，添加你需要的依赖包。文件中已经包含了使用提示。

agentkit config

配置 Agent 应用的参数。支持三种模式：交互式（友好引导）、非交互式（快速更新）和混合模式（灵活组合）。

🆕 全局配置支持：新增全局配置功能（~/.agentkit/config.yaml），可跨项目共享配置。

使用方法

bash

# 项目配置
agentkit config [参数] [选项]

# 全局配置 🆕
agentkit config --global [选项]

三种配置模式

🎯 交互式模式（默认，推荐首次配置）

无参数运行，系统会一步步引导你填写各项参数：

bash

agentkit config

交互流程示例：

[1/7] 🤖 Agent 名称: my_agent
[2/7] 📝 入口文件: my_agent.py  
[3/7] 📄 应用描述: 我的天气查询 Agent
[4/7] 🐍 Python 版本: 3.12
[5/7] 📦 依赖文件: requirements.txt
[6/7] 🚀 部署模式（选一个）:
  1. local - 本地构建和运行
  2. hybrid - 本地构建，云端运行
  3. cloud - 云端构建和运行（推荐）
[7/7] 🔐 应用级环境变量（所有模式共享）:
  变量: MODEL_API_KEY=xxxxx

⚡ 非交互式模式（快速更新，适合脚本/CI/CD）

通过命令行参数直接配置，无需手动输入：

bash

# 完整配置示例
agentkit config \
    --agent_name myAgent \
    --entry_point agent.py \
    --launch_type cloud \
    --image_tag v1.0.0 \
    --runtime_envs API_KEY=xxxxx

bash

# 增量更新（只修改部分配置）
agentkit config --entry_point new_agent.py
agentkit config --image_tag v1.0.1

🔀 混合模式

部分参数通过命令行指定，其他参数交互式输入：

bash

agentkit config --agent_name myAgent --interactive

主要参数

通用配置参数

参数	说明	示例
`--agent_name`	Agent应用名称	`my_weather_bot`
`--entry_point`	入口文件（必须 .py）	`agent.py`
`--description`	应用描述	`"天气查询助手"`
`--python_version`	Python版本	`3.12`
`--dependencies_file`	依赖文件	`requirements.txt`
`--launch_type`	部署模式	`local`, `hybrid`, `cloud`

环境变量配置（重要⭐）

AgentKit 支持两级环境变量配置：

参数	级别	说明	使用场景
`--runtime_envs` / `-e`	应用级	所有部署模式共享	API密钥、模型端点等跨环境配置
`--workflow-runtime-envs`	Workflow级	仅当前部署模式使用	调试标志、特定环境配置

使用示例：

bash

# 应用级（所有模式共享）
agentkit config \
    -e API_KEY=shared-key \
    -e MODEL_ENDPOINT=https://api.example.com

# Workflow级（仅当前模式）
agentkit config \
    --workflow-runtime-envs DEBUG=true \
    --workflow-runtime-envs LOCAL_CACHE=/tmp

# 混合使用
agentkit config \
    -e API_KEY=shared \
    --workflow-runtime-envs DEBUG=true

配置合并规则：

应用级环境变量被所有 workflow 继承
Workflow 级环境变量只在当前模式下生效
同名变量：Workflow 级覆盖应用级

Cloud/Hybrid 模式参数

参数	说明	示例
`--region`	火山引擎区域	`cn-beijing`
`--tos_bucket`	TOS存储桶	`agentkit-bucket`
`--image_tag`	镜像标签	`v1.0.0`, `latest`
`--cr_instance_name`	CR实例名称	`my-cr-instance`
`--cr_namespace_name`	CR命名空间	`agentkit`
`--cr_repo_name`	CR仓库名称	`my-agent`

💡 提示：--cr_* 参数也支持旧的 --ve_cr_* 别名，保持向后兼容。

控制选项

选项	说明
`--config`, `-c`	指定配置文件路径（默认 `agentkit.yaml`）
`--interactive`, `-i`	强制使用交互式模式
`--dry-run`	预览模式，显示变更但不保存
`--show`, `-s`	显示当前配置

全局配置选项 🆕

AgentKit 支持全局配置文件（~/.agentkit/config.yaml），用于跨项目共享配置。

选项	说明
`--global`, `-g`	操作全局配置而非项目配置
`--init`	初始化全局配置文件（创建模板）
`--set`	设置全局配置字段（格式：`key=value`）

支持的全局配置字段：

字段	说明	示例
`volcengine.access_key`	火山引擎 Access Key	`AK***`
`volcengine.secret_key`	火山引擎 Secret Key	`SK***`
`volcengine.region`	默认区域	`cn-beijing`
`cr.instance_name`	CR 实例名称	`team-cr-instance`
`cr.namespace_name`	CR 命名空间	`agentkit-team`
`tos.bucket`	TOS Bucket 名称	`team-agentkit-builds`
`tos.prefix`	TOS 对象前缀	`agentkit-builds`
`tos.region`	TOS 区域	`cn-beijing`

配置优先级：

环境变量 > 项目配置（agentkit.yaml） > 全局配置 > 默认值

使用示例

示例 1：首次配置（交互式）

bash

agentkit config

示例 2：快速更新单个配置项

bash

# 更新入口文件
agentkit config --entry_point new_agent.py

# 更新镜像标签
agentkit config --image_tag v1.0.1

# 添加环境变量
agentkit config -e NEW_KEY=new_value

示例 3：完整的非交互式配置

bash

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

示例 4：配置预览

bash

# 查看配置变更但不保存
agentkit config --entry_point agent.py --image_tag v2.0 --dry-run

输出示例：

通用配置 - 变更项:
┌───────────────┬──────────────┬──────────────┐
│ 配置项        │ 原值         │ 新值         │
├───────────────┼──────────────┼──────────────┤
│ entry_point   │ old_agent.py │ agent.py     │
│ image_tag     │ v1.0         │ v2.0         │
└───────────────┴──────────────┴──────────────┘

🔍 预览模式：未保存任何更改

示例 5：查看当前配置

bash

agentkit config --show

示例 6：全局配置管理 🆕

初始化全局配置：

bash

# 创建全局配置模板
agentkit config --global --init

输出：

✅ 全局配置文件已创建: ~/.agentkit/config.yaml

📝 配置模板已生成，包含以下配置项：

🔐 Volcengine 凭证
  access_key: ''
  secret_key: ''
  region: cn-beijing

📦 CR 配置
  instance_name: ''
  namespace_name: ''

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

查看全局配置：

bash

agentkit config --global --show

设置全局配置：

bash

# 设置单个字段
agentkit config --global --set cr.instance_name=team-cr-instance
agentkit config --global --set tos.bucket=team-bucket

# 设置凭证
agentkit config --global --set volcengine.access_key=AK***
agentkit config --global --set volcengine.secret_key=SK***

团队协作场景：

bash

# 1. 团队管理员创建并分享全局配置
agentkit config --global --init
vim ~/.agentkit/config.yaml  # 填入团队共享的配置

# 2. 团队成员初始化项目时自动使用全局配置
agentkit init my-agent
# agentkit.yaml 中相关字段自动留空，运行时使用全局配置

# 3. 特殊项目可以在 agentkit.yaml 中覆盖全局配置
agentkit config --cr_instance_name special-cr  # 覆盖全局配置

示例 7：CI/CD 集成

bash

# 在CI/CD流水线中使用
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

环境变量交互式输入

在交互式模式中，环境变量配置支持便捷命令：

🔐 应用级环境变量（输入 KEY=VALUE，空行结束）
  
  可用命令：
  - 输入 KEY=VALUE 添加变量
  - 输入 'list' 查看已有变量
  - 输入 'del KEY' 删除某个变量
  - 输入 'clear' 清空所有
  - 直接按回车结束输入

变量: MODEL_API_KEY=xxxxx
✅ 已添加: MODEL_API_KEY

变量: list
当前变量:
  MODEL_API_KEY=xxxxx

变量: [回车结束]
📋 共配置 1 个变量

配置验证

所有配置都会自动验证：

✅ 必填项检查：Agent名称、入口文件不能为空
✅ 格式验证：入口文件必须以 .py 结尾
✅ 选项约束：launch_type 必须是 local、hybrid 或 cloud
✅ 命名规范：Agent名称只能包含字母、数字、下划线、中划线和点

验证失败会显示详细错误信息并退出。

最佳实践

首次配置用交互式：更友好的引导体验
bash
```
agentkit config
```
日常修改用非交互式：快速高效
bash
```
agentkit config --entry_point new_agent.py
```

CI/CD用非交互式：完全自动化

bash

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

修改前先预览：避免错误

bash

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

环境变量分级管理：
- 应用级：API密钥等跨环境共享
- Workflow级：调试开关等特定环境配置

团队协作使用全局配置 🆕：

bash

# 团队管理员设置
agentkit config --global --init
agentkit config --global --set cr.instance_name=team-cr
agentkit config --global --set tos.bucket=team-bucket

# 团队成员直接使用
agentkit init my-agent  # 自动使用全局配置
agentkit launch         # 运行时自动使用全局配置

配置优先级理解：
- 项目配置可以覆盖全局配置
- 环境变量优先级最高
- 顺序：环境变量 > 项目配置 > 全局配置 > 默认值

agentkit build

将你的 Agent 代码打包成 Docker 镜像，为部署做准备。

使用方法

bash

agentkit build [选项]

参数说明

--config-file 配置文件路径

指定配置文件位置
默认：agentkit.yaml

--platform 构建平台

指定目标平台架构
默认：auto（自动识别）
一般不需要手动设置

--regenerate-dockerfile 强制重新生成 Dockerfile

强制重新生成 Dockerfile，即使已存在
适用场景：配置更新后需要强制刷新 Dockerfile
默认：False

Docker 构建自定义配置 🔧

AgentKit 支持通过 docker_build 配置段自定义 Docker 镜像构建过程。在 agentkit.yaml 中添加以下配置：

配置参数

base_image - 自定义基础镜像

Python 项目（字符串格式）：

yaml

docker_build:
  base_image: "python:3.12-slim"
  # 或使用 Alpine 镜像
  base_image: "python:3.12-alpine"

build_script - 自定义构建脚本

路径相对于项目根目录
用于安装系统依赖、编译扩展等
脚本会在构建过程中自动执行

yaml

docker_build:
  build_script: "scripts/setup.sh"

完整配置示例

Python 项目示例：

yaml

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

# Docker 构建自定义配置
docker_build:
  base_image: "python:3.12-alpine"
  build_script: "scripts/setup.sh"

构建脚本示例 (scripts/setup.sh)：

bash

#!/bin/bash
# 安装系统依赖
apt-get update && apt-get install -y gcc g++ libpq-dev
# 或 Alpine 系统使用：apk add --no-cache gcc musl-dev postgresql-dev

echo "Custom build script completed"

使用场景

场景	配置方式	示例
使用轻量级镜像	指定 Alpine 基础镜像	`base_image: "python:3.12-alpine"`
安装系统依赖	编写构建脚本	`build_script: "scripts/install_deps.sh"`
编译 C 扩展	安装编译工具	在脚本中安装 gcc、g++ 等
配置证书	更新 CA 证书	在脚本中运行 `update-ca-certificates`
多阶段构建	分别指定 builder 和 runtime	仅 Golang 项目支持

Dockerfile 自动管理

Dockerfile 会根据配置自动生成，包含元数据头
配置变化时自动更新（旧版本备份到 .agentkit/dockerfile_backups/）
删除元数据头后，AgentKit 不再自动管理该文件
使用 --regenerate-dockerfile 强制重新生成

元数据头示例：

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

构建过程

根据配置的 launch_type 自动选择构建方式：

🏠 Local 模式（本地构建）

在你的电脑上用 Docker 构建：

🔨 开始构建本地镜像...
[1/3] 生成 Dockerfile...
[2/3] Docker 构建镜像...
[3/3] 验证镜像可用性...
✅ 构建成功: my-agent:latest

预计耗时：1-3 分钟

☁️ Cloud 模式（云端构建）

在火山引擎上自动构建：

🔨 开始云端构建...
[1/6] 生成 Dockerfile...
[2/6] 打包项目代码...
[3/6] 上传到对象存储...
[4/6] 准备镜像仓库...
[5/6] 创建构建流水线...
[6/6] 执行构建任务...
✅ 构建成功: xxx.cr.volces.com/agentkit/my-agent:latest

预计耗时：3-5 分钟

构建结果

镜像名称：{agent_name}:{image_tag}
镜像信息：自动保存到配置文件
构建记录：包含时间戳、镜像 ID 等

使用示例

bash

# 示例 1：使用默认配置
agentkit build

# 示例 2：指定配置文件
agentkit build --config-file ./prod.yaml

# 示例 3：强制重新生成 Dockerfile
agentkit build --regenerate-dockerfile

# 示例 4：配置更新后强制刷新
agentkit build --config-file ./prod.yaml --regenerate-dockerfile

自定义构建示例

示例 5：使用 Alpine 基础镜像

修改 agentkit.yaml：

yaml

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

创建 scripts/alpine-setup.sh：

bash

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

构建：

bash

agentkit build

示例 6：安装系统依赖（C 扩展）

修改 agentkit.yaml：

yaml

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

创建 scripts/install-deps.sh：

bash

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

构建：

bash

agentkit build

示例 7：Golang 多阶段构建

修改 agentkit.yaml：

yaml

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

构建：

bash

agentkit build

注意事项

Local 模式前提：

✅ 确保 Docker 已安装并运行
✅ Docker daemon 可正常访问

Cloud 模式前提：

✅ 设置 AK/SK 环境变量
✅ 确保网络能访问火山引擎

Docker 构建自定义：

✅ 构建脚本的路径，请填写相对于项目根目录的相对路径
✅ 脚本会自动获得执行权限
✅ 构建脚本不存在会记录警告但不会中断构建
✅ Dockerfile 自动生成，配置变化时自动更新
✅ 旧版本 Dockerfile 会备份到 .agentkit/dockerfile_backups/
✅ 删除 Dockerfile 元数据头后不再自动管理

提示：构建信息会自动更新到配置文件，供 deploy 命令使用

agentkit deploy

将构建好的镜像启动运行，让 Agent 对外提供服务。

使用方法

bash

agentkit deploy [选项]

参数说明

--config-file 配置文件路径

指定配置文件位置
默认：agentkit.yaml

部署过程

根据配置的 launch_type 自动选择部署目标：

🏠 Local 模式（本地部署）

在你的电脑上启动容器：

🚀 开始部署到本地 Docker...
[1/3] 停止旧版本容器...
[2/3] 启动新容器...
[3/3] 验证容器状态...
✅ 部署成功！容器正在运行
🌐 访问地址: http://localhost:8000

预计耗时：10-30 秒

☁️ Cloud 模式（云端部署）

在火山引擎上创建 Runtime：

🚀 开始部署到云端平台...
✅ 生成 Runtime 名称: my-agent-20250120-abc123
✅ 创建 Runtime: r-xxxxxx
⏳ 等待 Runtime 就绪...
✅ Runtime 已就绪！
🌐 访问地址: http://xxx.apigateway-cn-beijing.volceapi.com

预计耗时：1-2 分钟

使用示例

bash

# 示例 1：部署到默认环境
agentkit deploy

# 示例 2：部署到生产环境
agentkit deploy --config-file ./prod.yaml

部署完成后

Local 模式：

✅ 容器在本地运行
✅ 可通过 localhost:端口 访问
✅ 自动进行健康检查

Cloud 模式：

✅ Runtime 在云端运行
✅ 获得一个公网可访问的 URL
✅ 自动验证 Runtime 状态

agentkit launch

构建 + 部署，一步完成！相当于自动执行 build 再执行 deploy。

使用方法

bash

agentkit launch [选项]

参数说明

--config-file 配置文件路径

指定配置文件位置
默认：agentkit.yaml

执行流程

🚀 开始启动 Agent...

━━━ 第一步：构建镜像 ━━━
🔨 读取配置: agentkit.yaml
🔨 开始构建...
✅ 构建完成

━━━ 第二步：部署应用 ━━━
🚀 开始部署...
✅ 部署完成

✨ Agent 已成功启动！

使用示例

bash

# 示例 1：一键启动
agentkit launch

# 示例 2：启动到生产环境
agentkit launch --config-file ./prod.yaml

为什么用 launch

⚡ 省时省力 - 一个命令代替两个
🔒 版本一致 - 确保构建和部署使用同一配置
🚀 快速迭代 - 改完代码立即测试

agentkit invoke

向已部署的 Agent 发送测试请求，验证功能是否正常。

使用方法

bash

agentkit invoke [消息内容] [选项]

⚠️ 重要：必须提供消息内容或 --payload 选项之一，两者不能同时使用

参数说明

消息内容

直接在命令后面输入要发送的文字，不需要加任何选项标记
会自动包装成 {"prompt": "你的消息"}
不能和 --payload 同时使用
示例：agentkit invoke "你好" 或 agentkit invoke "今天天气怎么样？"

选项

--payload, -p 自定义请求数据

用 JSON 格式指定完整的请求内容
不能和消息内容同时使用
示例：--payload '{"prompt": "你好", "context": "greeting"}'

--headers, -h 自定义请求头

用 JSON 格式指定 HTTP 请求头
默认会自动添加 user_id 和 session_id
示例：--headers '{"user_id": "test123"}'

--apikey, -ak API 密钥

云端部署（Cloud 模式）时可能需要
用于身份验证
可选参数

--config-file 配置文件路径

指定配置文件位置
默认：当前目录的 agentkit.yaml

使用示例

示例 1：直接发送消息（最简单）

bash

agentkit invoke "今天杭州天气如何？"

等同于发送以下 JSON：

json

{
  "prompt": "今天杭州天气如何？"
}

示例 2：自定义请求内容

bash

agentkit invoke --payload '{"prompt": "杭州天气?", "user_location": "杭州"}'

示例 3：带请求头

bash

agentkit invoke \
  --payload '{"prompt": "杭州天气?"}' \
  --headers '{"user_id": "user123", "session_id": "sess456"}'

示例 4：云端部署（带 API Key）

bash

agentkit invoke "你好" --apikey your_api_key_here

运行效果

💬 正在调用 Agent...
✅ Runtime ID: r-xxxxxx
🌐 调用地址: http://xxx.apigateway-cn-beijing.volceapi.com
✅ 调用成功！

📡 Agent 响应:
杭州今天天气晴，温度 22°C，适合出行。

注意事项

⚠️ 消息内容和 --payload 只能选一个
⚠️ 云端部署可能需要 API Key
⚠️ 调用前确保 Agent 已部署（用 agentkit status 检查）

agentkit status

查看 Agent 的运行状态，包括是否在线、访问地址等信息。

使用方法

bash

agentkit status [选项]

参数说明

--config-file 配置文件路径

指定配置文件位置
默认：agentkit.yaml

输出示例

🏠 Local 模式

✅ 容器名称: my-agent
✅ 运行状态: running
🌐 访问地址: http://localhost:8000

详细信息：
{
    "container_id": "abc123...",
    "status": "running",
    "ports": ["8000:8000"],
    "created": "2025-01-20 10:00:00",
    "health": "healthy"
}

☁️ Cloud 模式

✅ Runtime ID: r-xxxxxx
✅ 运行状态: Ready
🌐 访问地址: http://xxx.apigateway-cn-beijing.volceapi.com

详细信息：
{
    "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"
}

状态说明

Local 模式状态：

✅ running - 正常运行中
⏸️ stopped - 已停止
🔄 restarting - 重启中
❌ error - 出现错误

Cloud 模式状态：

✅ Ready - 就绪，可接收请求
🔄 Releasing - 正在部署
❌ Error - 运行错误
❌ Failed - 部署失败

使用示例

bash

# 示例 1：查看当前状态
agentkit status

# 示例 2：查看生产环境状态
agentkit status --config-file ./prod.yaml

agentkit destroy

停止并删除 Agent 实例，释放资源。⚠️ 这是不可逆操作！

使用方法

bash

agentkit destroy [选项]

参数说明

--force 强制删除

跳过确认提示，直接删除
默认不开启（会要求确认）
谨慎使用！

--config-file 配置文件路径

指定配置文件位置
默认：agentkit.yaml

安全确认

默认会要求你确认操作：

🗑️ 准备销毁运行中的 Agent...
⚠️ 此操作不可恢复！
确定要继续吗？[y/N]: y

跳过确认（不推荐）：

bash

agentkit destroy --force

会删除什么

🏠 Local 模式

✅ 停止 Docker 容器
✅ 删除容器实例
⚠️ 镜像会保留（可手动删除）

☁️ Cloud 模式

✅ 删除 Runtime 实例
✅ 释放云端资源
⚠️ 镜像会保留（可在 CR 中手动删除）

运行效果

🗑️ 开始销毁 Agent 资源...
✅ 停止 Runtime: r-xxxxxx
✅ 删除 Runtime 成功
✅ 资源已清理完成

提示：配置文件和镜像已保留，可随时重新部署。

使用示例

bash

# 示例 1：安全删除（推荐）
agentkit destroy

# 示例 2：强制删除
agentkit destroy --force

# 示例 3：删除指定环境
agentkit destroy --config-file ./dev.yaml

重要提示

⚠️ 不可恢复：删除后无法撤销，数据将永久丢失
✅ 配置保留：agentkit.yaml 文件不会被删除
✅ 镜像保留：Docker 镜像不会被删除，可重新部署
💡 重新部署：随时可以用 agentkit deploy 重新部署

通用选项

所有命令都支持这些选项：

--help 查看帮助

查看任何命令的详细说明和参数：

bash

# 查看某个命令的帮助
agentkit invoke --help
agentkit build --help

# 查看所有命令列表
agentkit --help

--version 查看版本

显示 CLI 版本信息：

bash

agentkit --version
# 或
agentkit -v

常用工作流

📝 完整开发流程（模板模式）

从零开始到上线的完整步骤：

bash

# 1️⃣ 创建项目
agentkit init weather_agent --template basic
cd weather_agent

# 2️⃣ 配置应用
agentkit config

# 3️⃣ 一键部署
agentkit launch

# 4️⃣ 测试功能
agentkit invoke "杭州天气怎么样？"

# 5️⃣ 查看状态
agentkit status

🔄 快速部署已有 Agent（包装模式）🆕

将现有的 Agent 快速部署上线：

bash

# 1️⃣ 包装现有 Agent 文件
agentkit init --from-agent ~/my_projects/weather_agent.py

# 2️⃣ 进入项目目录
cd agentkit-weather_agent

# 3️⃣ （可选）配置应用
agentkit config

# 4️⃣ 一键部署
agentkit launch

# 5️⃣ 测试功能
agentkit invoke "今天天气如何？"

# 6️⃣ 查看状态
agentkit status

🔄 快速迭代流程

修改代码后的更新流程：

bash

# 方式 1：分步执行（推荐调试时使用）
agentkit build        # 重新构建
agentkit deploy       # 重新部署
agentkit invoke "测试"  # 测试验证

# 方式 2：一键更新（推荐日常开发）
agentkit launch       # 自动构建+部署
agentkit invoke "测试"  # 测试验证

🌍 多环境管理

在开发、测试、生产环境间切换：

bash

# 开发环境
agentkit launch --config-file agentkit.dev.yaml
agentkit invoke "测试" --config-file agentkit.dev.yaml

# 生产环境
agentkit launch --config-file agentkit.prod.yaml
agentkit invoke "测试" --config-file agentkit.prod.yaml

常见问题

遇到错误不要慌，这里有解决方案！

❌ 配置文件找不到

Error: Configuration file not found: agentkit.yaml

原因：当前目录没有配置文件

解决：

bash

# 如果是新项目
agentkit init my_agent

# 如果已有项目
agentkit config

❌ Docker 没有运行（Local 模式）

Error: Docker daemon not running

原因：Docker 服务未启动

解决：

Windows/Mac：打开 Docker Desktop
Linux：sudo systemctl start docker

❌ 云端凭证未配置（Cloud 模式）

Error: VOLC_ACCESSKEY or VOLC_SECRETKEY not set

原因：没有设置火山引擎 AK/SK

解决：

bash

export VOLC_ACCESSKEY="你的AccessKey"
export VOLC_SECRETKEY="你的SecretKey"

❌ 构建失败

❌ 构建失败: ...

可能原因和解决方案：

依赖问题 - 检查 requirements.txt 是否正确
代码错误 - 检查 Python 代码是否有语法错误
网络问题 - 检查网络连接，重试构建
权限问题 - 确保有 Docker/云端的操作权限

💡 调试技巧

1. 查看详细日志

bash

# 设置详细日志级别
export LOG_LEVEL=DEBUG
agentkit build

2. 验证配置文件

bash

# 检查配置是否正确
cat agentkit.yaml

3. 分步执行

bash

# 分开执行，更容易定位问题
agentkit build    # 先构建
agentkit deploy   # 再部署
# 而不是直接用 launch

4. 检查运行状态

bash

# 查看 Agent 是否正常运行
agentkit status

下一步

📖 配置文件说明 - 深入了解每个配置项
🚀 快速开始 - 跟随教程实践
❓ 问题排查 - 更多疑难问题解答

CLI 命令详解 ​

命令总览 ​

agentkit init ​

使用模式 ​

命令格式 ​

核心参数 ​

模板模式选项 ​

包装模式选项 ​

通用选项 ​

使用示例 ​

模板模式 ​

包装模式 ​

运行效果 ​

模板模式输出 ​

包装模式输出 🆕 ​

包装模式详解 🆕 ​

工作原理 ​

包装器的作用 ​

Agent 文件要求 ​

包装器类型对比 ​

使用场景 ​

包装后的项目结构 ​

常见问题 ​

agentkit config ​

使用方法 ​

三种配置模式 ​

🎯 交互式模式（默认，推荐首次配置） ​

⚡ 非交互式模式（快速更新，适合脚本/CI/CD） ​

🔀 混合模式 ​

主要参数 ​

通用配置参数 ​

环境变量配置（重要⭐） ​

Cloud/Hybrid 模式参数 ​

控制选项 ​

全局配置选项 🆕 ​

使用示例 ​

示例 1：首次配置（交互式） ​

示例 2：快速更新单个配置项 ​

示例 3：完整的非交互式配置 ​

示例 4：配置预览 ​

示例 5：查看当前配置 ​

示例 6：全局配置管理 🆕 ​

示例 7：CI/CD 集成 ​

环境变量交互式输入 ​

配置验证 ​

最佳实践 ​

agentkit build ​

使用方法 ​

参数说明 ​

Docker 构建自定义配置 🔧 ​

配置参数 ​

完整配置示例 ​

使用场景 ​

Dockerfile 自动管理 ​

构建过程 ​

🏠 Local 模式（本地构建） ​

☁️ Cloud 模式（云端构建） ​

构建结果 ​

使用示例 ​

自定义构建示例 ​

注意事项 ​

agentkit deploy ​

使用方法 ​

参数说明 ​

部署过程 ​

🏠 Local 模式（本地部署） ​

☁️ Cloud 模式（云端部署） ​

使用示例 ​

部署完成后 ​

agentkit launch ​

使用方法 ​

参数说明 ​

执行流程 ​

使用示例 ​

为什么用 launch ​

agentkit invoke ​

使用方法 ​

参数说明 ​

使用示例 ​

示例 1：直接发送消息（最简单） ​

CLI 命令详解

命令总览

`agentkit init`

使用模式

命令格式

核心参数

模板模式选项

包装模式选项

通用选项

使用示例

模板模式

包装模式

运行效果

模板模式输出

包装模式输出 🆕

包装模式详解 🆕

工作原理

包装器的作用

Agent 文件要求

包装器类型对比

使用场景

包装后的项目结构

常见问题

agentkit config

使用方法

三种配置模式

🎯 交互式模式（默认，推荐首次配置）

⚡ 非交互式模式（快速更新，适合脚本/CI/CD）

🔀 混合模式

主要参数

通用配置参数

环境变量配置（重要⭐）

Cloud/Hybrid 模式参数

控制选项

全局配置选项 🆕

使用示例

示例 1：首次配置（交互式）

示例 2：快速更新单个配置项

示例 3：完整的非交互式配置

示例 4：配置预览

示例 5：查看当前配置

示例 6：全局配置管理 🆕

示例 7：CI/CD 集成

环境变量交互式输入

配置验证

最佳实践

agentkit build

使用方法

参数说明

Docker 构建自定义配置 🔧

配置参数

完整配置示例

使用场景

Dockerfile 自动管理

构建过程

🏠 Local 模式（本地构建）

☁️ Cloud 模式（云端构建）

构建结果

使用示例

自定义构建示例

注意事项

agentkit deploy

使用方法

参数说明

部署过程

🏠 Local 模式（本地部署）

☁️ Cloud 模式（云端部署）

使用示例

部署完成后

agentkit launch

使用方法

参数说明

执行流程

使用示例

为什么用 launch

agentkit invoke

使用方法

参数说明

使用示例

示例 1：直接发送消息（最简单）