`agentkit config`命令用于配置Agent应用的参数。 ## 支持的配置模式 * 项目配置：支持**交互式**（友好引导）、**非交互式**（快速更新）和**混合模式**（灵活组合）。 * 全局配置：全局配置功能（`~/.agentkit/config.yaml`），可跨项目共享配置。 ## **配置优先级** * 项目配置可以覆盖全局配置。 * 环境变量优先级最高。 * 顺序：环境变量 \> 项目配置（`agentkit.yaml`） \> 全局配置（`~/.agentkit/config.yaml`） \> 默认值。 ## 使用方法 ```Bash # 项目配置 agentkit config [参数] [选项] # 全局配置 agentkit config --global [选项] ``` ## 项目配置模式 ### 交互式模式（默认，推荐首次配置）无参数运行，系统会一步步引导您填写各项参数： ```Bash agentkit config ``` **交互流程** ```Plain Text [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 |\ | || |\ | |* local：本地构建和部署。| |\ | |* hybrid：本地构建，云端部署。| |\ | |* cloud：云端构建和部署。 | | #### 环境变量配置 AgentKit支持**应用级和Workflow级环境变量**配置： |**参数** |**级别** |**说明** |**使用场景** | |---|---|---|---| |`--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_*`别名，保持向后兼容。 ### Runtime关联资源（Cloud/Hybrid）你可以通过`agentkit config`将Runtime与资源组件进行关联（或解绑），在`agentkit launch/deploy`创建/更新Runtime时自动透传到Runtime API。支持的关联字段： * `memory_id`：关联Memory。 * `knowledge_id`：关联Knowledge。 * `tool_id`：关联Tool。 * `mcp_toolset_id`：关联MCP Toolset。 **命令行配置示例**： ```Bash # 绑定资源 agentkit config \ --memory_id mem-xxxx \ --knowledge_id kb-xxxx \ --tool_id tool-xxxx \ --mcp_toolset_id mcp-ts-xxxx # 解绑（设置为空字符串） agentkit config --memory_id "" ``` **YAML落盘位置**（`agentkit.yaml`）： ```YAML launch_types: cloud: # 或 hybrid runtime_bindings: memory_id: mem-xxxx knowledge_id: kb-xxxx tool_id: tool-xxxx mcp_toolset_id: mcp-ts-xxxx ``` > **解绑说明** > * 配置里**不写某个key**：表示不变更该绑定。 > * 配置为`""`或`null`：表示清空/解绑（会在更新 Runtime 时下发清空）。 ### Runtime网络配置（Cloud/Hybrid）你可以通过`agentkit config`为Runtime设置网络（VPC/私网、公网或双栈）。该配置会在**首次创建 Runtime（CreateRuntime）** 时生效。 :::tip 当Runtime已存在时，执行`agentkit launch/deploy`会调用UpdateRuntime逻辑，但UpdateRuntime不支持修改 `network_configuration`，所以该配置变更无法生效到已创建的Runtime的网络配置。如需变更网络配置，请先销毁现有Runtime，再重新创建Runtime。 ::: **命令行配置示例（私网）** ： ```Bash agentkit config \ --runtime-network-mode private \ --runtime-vpc-id vpc-xxxxxxxx \ --runtime-subnet-id subnet-aaaaaaaa ``` **YAML 配置格式**（`agentkit.yaml`）： ```YAML launch_types: cloud: # 或 hybrid runtime_network: mode: private # public | private | both vpc_id: vpc-xxxxxxxx # private/both 必填 subnet_ids: - subnet-aaaaaaaa ``` `mode`取值说明： * `public`：仅公网访问。 * `private`：仅私网访问（需要`vpc_id`）。 * `both`：同时开启公网与私网（需要`vpc_id`）。 ### 控制选项 |**选项** |**说明** | |---|---| |`--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 | ## 使用示例 ### 示例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 ``` 输出示例： ```Plain Text 通用配置 - 变更项: ┌───────────────┬──────────────┬──────────────┐ │ 配置项 │ 原值 │ 新值 │ ├───────────────┼──────────────┼──────────────┤ │ entry_point │ old_agent.py │ agent.py │ │ image_tag │ v1.0 │ v2.0 │ └───────────────┴──────────────┴──────────────┘ 🔍 预览模式：未保存任何更改 ``` ### 示例5：查看当前配置 ```Bash agentkit config --show ``` ### 示例6：全局配置管理 * **初始化全局配置** ```Bash # 创建全局配置模板 agentkit config --global --init ``` 输出示例： ```Plain Text ✅ 全局配置文件已创建: ~/.agentkit/config.yaml 📝 配置模板已生成，包含以下配置项： 🔐 Volcengine 凭证 access_key: '' secret_key: '' region: cn-beijing 📦 CR 配置 instance_name: '' namespace_name: '' 🗂️ TOS 配置 bucket: '' prefix: agentkit-builds region: cn-beijing ``` * **查看全局配置：** ```Plain Text 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 ``` ## 环境变量交互式输入在交互式模式中，环境变量配置支持便捷命令： ```Plain Text 🔐 应用级环境变量（输入 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名称只能包含字母、数字、下划线、中划线和点。验证失败会显示详细错误信息并退出。 ## 最佳实践 1. **首次配置用交互式，** 更友好的引导体验。 ```Bash agentkit config ``` 2. **日常修改用非交互式，** 快速高效。 ```Bash agentkit config --entry_point new_agent.py ``` 3. **CI/CD用非交互式，** 完全自动化。 ```Bash agentkit config --agent_name $PROJECT --image_tag $TAG ``` 4. **修改前先预览，** 避免错误。 ```Bash agentkit config --entry_point agent.py --dry-run ``` 5. **环境变量分级管理。** * 应用级：API密钥等跨环境共享。 * Workflow级：调试开关等特定环境配置。 6. **团队协作使用全局配置。** ```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 # 运行时自动使用全局配置 ```