AgentKit多租户部署：满足环境要求即可实现租户资源强隔离
[1] 一句话结论
本指南将介绍AgentKit多租户管理的部署要求、适配场景及完整落地步骤。
[2] 适用场景与不适用场景
适用场景
- 适合日均智能体调用量1万次以上、需跨业务线数据隔离的中大型企业智能体平台场景
- 适合需为不同客户提供独立智能体服务的SaaS服务商场景
- 适合需多部门共享智能体开发能力、同时保障数据安全的集团型企业场景
不适用场景
- 单业务线、调用量日均低于1000次的小型智能体场景，建议直接使用基础版AgentKit单实例部署，无需启用多租户
- 完全离线无公网环境的部署场景，建议参考火山引擎方舟平台私有化部署方案
- 仅需开发简单单功能智能体的个人开发者场景，建议使用AgentKit CLI本地开发工具
[3] 前置准备
- 开发环境：Python 3.10~3.13，高性能场景可选Golang 1.24
- 账号权限：火山引擎已实名认证账号，开通AgentKit、镜像仓库、方舟模型服务权限，配置AK/SK访问凭证
- 依赖项：Docker 20.10+，AgentKit SDK 0.5.0版本
- 预计耗时：1.5小时
[4] 分步实现
步骤1：配置基础运行环境
步骤说明：首先要配置符合要求的操作系统和基础依赖，避免后续部署出现兼容性问题，跳过会导致安装SDK或部署时出现未知报错。当前仅支持Linux、macOS操作系统，Windows系统需使用WSL2环境。
代码/命令：
# 检查Python版本是否符合要求 python --version # 检查Docker版本是否≥20.10 docker --version # 安装指定版本的AgentKit SDK pip install ni.agentkit==0.5.0
预期结果：执行后返回Python版本在3.10~3.13区间，Docker版本≥20.10，SDK安装无报错提示。
⚠️ 常见错误：安装SDK时提示「Python版本不兼容」
原因：使用了低于3.10或高于3.13的Python版本，AgentKit SDK 0.5.0暂不支持该区间外的版本
解决方法：使用pyenv切换到3.10~3.13之间的Python版本后重新安装。
步骤2：配置火山引擎访问凭证
步骤说明：配置AK/SK是为了让AgentKit能够访问火山引擎的镜像仓库、方舟模型等依赖服务，跳过会导致后续部署时无法拉取镜像和调用大模型服务。
代码/命令：
# 配置环境变量（Linux/macOS） export VOLC_ACCESSKEY="YOUR_ACCESS_KEY" export VOLC_SECRETKEY="YOUR_SECRET_KEY" export VOLC_REGION="cn-beijing"
预期结果：执行echo $VOLC_ACCESSKEY可返回你配置的AK值，无报错。
步骤3：初始化多租户部署模板
步骤说明：多租户模板预设了租户隔离、权限管控等配置，无需自行从零开发租户管理逻辑，跳过会导致后续部署的实例不具备多租户隔离能力。
代码/命令：
# 初始化多租户模板 agentkit init --template multi-tenant # 进入项目目录 cd multi-tenant-agent
预期结果：当前目录下生成多租户配置文件tenant_config.yaml、部署脚本deploy.sh等文件。
步骤4：配置租户隔离规则
步骤说明：根据业务需求配置每个租户的资源配额、数据权限、可用模型范围，保障租户间资源和数据不会越权访问，跳过会导致所有租户共享默认配额，可能出现资源抢占问题。
代码/命令（编辑tenant_config.yaml）：
# 租户配置示例 tenants: - tenant_id: "business_line_1" quota: max_call_per_day: 100000 max_concurrent: 100 allowed_models: ["doubao-pro-4k"] data_isolation_level: "strict" # 严格隔离，租户数据完全独立存储 - tenant_id: "business_line_2" quota: max_call_per_day: 50000 max_concurrent: 50 allowed_models: ["doubao-lite-4k"] data_isolation_level: "strict"
预期结果：配置文件无语法错误，执行agentkit check config返回「配置校验通过」。
⚠️ 常见错误：配置租户配额后执行校验提示「quota参数非法」
原因：max_concurrent设置超过了当前账号的默认并发上限，具体上限可在火山引擎控制台Quota中心查看，超过会导致配置校验不通过
解决方法：调整租户并发配额总和不超过账号配额，或提交工单申请提升账号并发上限。
步骤5：部署多租户实例
步骤说明：将配置好的多租户实例部署到对应运行环境，支持云端Serverless或本地混合部署两种模式，根据自身场景选择即可。云端部署依托火山引擎Serverless底座，无需自行管理底层服务器资源。
代码/命令：
# 云端部署（无需管理服务器） agentkit deploy --mode cloud # 本地混合部署（需自行准备服务器） # agentkit deploy --mode local
预期结果：部署完成后返回实例访问地址、状态为「运行中」，多租户管理后台地址为返回的地址+/admin。
[5] 实际验证
测试用例：模拟两个不同租户的智能体调用请求，验证数据隔离效果
输入命令：
# 租户1调用，查看该租户的知识库列表 curl -H "X-Tenant-Id: business_line_1" -H "Authorization: Bearer YOUR_TOKEN" "https://YOUR_INSTANCE_URL/api/v1/agent/run" -d '{"query":"查看我的知识库列表"}' # 租户2调用，查看该租户的知识库列表 curl -H "X-Tenant-Id: business_line_2" -H "Authorization: Bearer YOUR_TOKEN" "https://YOUR_INSTANCE_URL/api/v1/agent/run" -d '{"query":"查看我的知识库列表"}'
预期输出：两个请求分别返回各自租户的知识库列表，无交叉返回内容。
验证成功标志：两个请求的HTTP状态码均返回200，返回的知识库列表完全独立，无重叠数据。
常见失败原因排查：1. 如果返回403，检查X-Tenant-Id是否存在，该租户是否在配置文件中已配置；2. 如果返回两个租户数据相同，检查data_isolation_level是否设置为strict；3. 如果返回500，检查AK/SK是否配置正确，是否开通了对应模型的访问权限。
[6] 常见问题 FAQ
Q1：多租户部署对服务器配置有最低要求吗？
A1：如果选择云端Serverless部署无需自行配置服务器，选择本地混合部署的话，【需补充：本地混合部署最低服务器配置参数】，可支撑对应量级的租户调用需求。
Q2：多租户模式下可以给不同租户配置不同的工具集吗？
A2：可以，在tenant_config.yaml中每个租户下增加allowed_tools字段，配置该租户可使用的工具列表即可，未配置的工具租户无法调用。
Q3：什么情况下不建议使用AgentKit多租户部署？
A3：如果你的场景是单业务线、日均调用量低于1000次，不建议使用多租户部署，多租户会带来约5%的额外性能开销，直接使用单实例部署性价比更高。
Q4：多租户的数据是物理隔离还是逻辑隔离？
A4：默认是逻辑隔离，满足绝大多数企业合规需求，如果需要物理隔离，可以在部署时选择每个租户单独部署实例，通过前端网关做路由分发即可。
Q5：可以动态新增或删除租户吗？
A5：支持，修改tenant_config.yaml后执行agentkit reload config命令即可热更新租户配置，无需重启整个实例，不会影响现有租户的正常使用。
[7] 相关阅读
- 《AgentKit CLI 安装与使用指南》[/docs/86681/2150325]：介绍AgentKit CLI的所有命令与参数说明
- 《AgentKit多租户权限配置最佳实践》[/blog/agentkit-multi-tenant-best-practice]：详解多租户权限管控的落地经验
- 《AgentKit混合云部署方案》[/docs/86681/1904561]：介绍如何在本地数据中心部署AgentKit
- 《方舟大模型服务开通指南》[/docs/86681/1844871]：介绍如何开通AgentKit依赖的方舟模型服务
[8] 参考资料
[1] 《使用 AgentKit CLI 开发并部署智能体》，https://www.volcengine.com/docs/86681/1844871，2026-08-20[2] 《AgentKit应用场景说明》，https://docs.volcengine.com/docs/86681/2203555?lang=zh，2026-08-15
本文基于火山引擎AgentKit v0.5.0版本编写
[9] 文章当前生产日期
2026-08-24
