企业级多 Agent 协同项目的复杂度往往不是单个 Agent 能力不够而是多个 Agent 之间缺乏可靠的约束机制谁在什么权限下执行、运行环境是否能被隔离、技能如何沉淀与复用、关键时刻能否让人介入。这次我们看的方向是 Harness Engineering它强调的不是让 Agent 自由发挥而是像给马套上缰绳一样在可控框架里做多 Agent 协同、沙箱隔离、Skill 自进化、人工介入。这套思路直接面向 AI Agent 工程化落地而不是停留在 Demo 层面。文章会围绕几个核心问题展开多 Agent 协同的工程化架构怎么搭、沙箱为什么是 Agent 安全的底线、Skill 如何设计与自进化、人在回路怎么介入、批量任务和 API 接口怎么接。如果你正在做 AI Agent 开发或者需要把 Agent 系统接入企业内部流程这篇文章建议直接收藏。1. 核心能力速览能力项说明项目类型企业级多 Agent 协同框架Harness Engineering 实战核心功能多 Agent 编排、沙箱隔离、Skill 自进化、人工介入、批量任务主要特点用约束机制控制 Agent 行为而不是完全依赖模型自由发挥关键组件Agent 运行时、沙箱环境、Skill 管理器、人工审批流、任务队列硬件要求取决于底层模型CPU 可运行部分编排逻辑GPU 影响推理速度显存占用需按实际模型版本和推理参数测试无固定值支持平台Linux / macOS / Windows以 Docker 为最佳运行环境启动方式Docker Compose / 命令行 / WebUI / API 服务是否支持 API支持可通过 HTTP 接口触发 Agent 任务是否支持批量任务支持可通过任务队列和目录扫描触发适合场景企业内部流程自动化、Agent 安全执行、多角色任务协作、需要人工审批的任务2. 适用场景与使用边界这套方案适合哪类人我觉得可以从三个角度去看。第一类是已经在做 AI Agent 开发但发现单 Agent 处理复杂任务时上下文容易混乱、任务容易断需要引入多 Agent 分工。比如一个 Agent 负责代码分析一个 Agent 负责执行测试另一个 Agent 负责汇总报告这就需要一个编排层来管理它们之间的通信。第二类是准备把 Agent 接入企业内部系统的人。企业内部系统对权限、安全、审计有很高要求Agent 不能随便执行命令、不能访问未授权目录、更不能绕过审批直接改数据库。Harness Engineering 里强调的沙箱隔离和人工介入恰好对应这一层需求。第三类是研究如何让 Agent 持续进化的人。自进化 Skill 的意思是Agent 在完成任务后把有效的步骤沉淀为可复用的技能下次遇到类似任务可以直接调用。这解决了 Agent 记忆和复用的问题。但也要说清楚边界。这套方案不适合完全无人值守的高风险任务比如自动转账、自动发布生产环境、自动修改核心配置。这类场景必须有审批节点也就是人必须在关键步骤介入。另外如果任务非常单一、上下文很短引入多 Agent 反而会增加延迟和成本简单问题用单 Agent 处理更合适。合规和安全方面必须强调如果你把 Agent 接入实际业务涉及用户数据、公司内部资料、代码仓库要确保有授权和审计记录。如果 Agent 需要处理人脸、声音、文档等敏感信息必须确认数据来源合法、使用目的明确、存储方式安全。沙箱能隔离执行环境但不能替代合规流程。3. 环境准备与前置条件3.1 基础运行环境这个方案本质上是一套 Agent 工程化框架底层可以接不同的大模型。所以环境准备要看两层一层是 Agent 编排框架本身另一层是接的推理服务。建议的基础环境清单依赖项建议要求说明操作系统Linux 优先macOS / Windows 可用 DockerLinux 对沙箱和容器支持更稳定Docker20.10 以上沙箱核心依赖容器化Docker Compose2.0 以上多服务编排方便启动Python3.10 / 3.11Agent 脚本和 Skill 运行环境CUDA按实际模型要求仅 GPU 推理时需要Node.js16部分 WebUI 组件可能需要磁盘空间至少 20GB模型文件、日志、临时文件内存16GB 起步多 Agent 并发时建议 32GB3.2 沙箱环境准备沙箱是这套架构里的核心安全层。常见实现有几种Docker 容器沙箱每个 Agent 任务跑在独立容器里隔离文件系统和网络。Wasm 沙箱适合纯计算类任务启动快资源占用低。受限系统用户用 Linux 低权限用户执行命令控制在指定目录内。从实际部署经验看Docker 沙箱最稳妥因为文件系统、网络、进程都可以隔离。Wasm 沙箱适合 Skill 里那些无状态的计算函数比如 JSON 处理、格式转换、文本提取。更稳妥的方案是组合使用Agent 编排层用 Docker 沙箱跑主任务Skill 内部的小工具用 Wasm 沙箱跑。3.3 模型推理服务准备这个框架本身不内置大模型需要提前准备好一个可用的推理服务。选择取决于你的场景如果是在云端可以用 OpenAI 兼容接口只需要配置 API Key。如果本地部署需要准备一个可用的模型服务比如用 vLLM 或同类工具启动一个支持 OpenAI 协议的服务。部署前先确认推理服务的端口和模型名称因为 Agent 编排框架通过环境变量或者配置文件来连模型服务。4. 安装部署与启动方式4.1 Docker Compose 部署这是推荐的方式。多 Agent 协同系统至少包含下面几个服务orchestrator编排层负责 Agent 调度和状态管理。agent-runner执行层负责跑 Agent。sandbox-manager沙箱管理负责分配和回收容器。skill-store技能仓库负责 Skill 的加载和索引。web-ui人工介入界面。api-server外部接口服务。典型的 docker-compose 配置结构version: 3.8 services: orchestrator: image: your-agent-orchestrator:latest container_name: agent-orchestrator ports: - 8000:8000 environment: - MODEL_API_BASEhttp://your-llm-service:8001/v1 - MODEL_NAMEqwen2.5-72b-instruct - SANDBOX_TYPEdocker - SKILL_DIR/data/skills volumes: - ./data/skills:/data/skills - ./data/tasks:/data/tasks depends_on: - sandbox-manager - skill-store sandbox-manager: image: your-sandbox-manager:latest container_name: sandbox-manager volumes: - /var/run/docker.sock:/var/run/docker.sock skill-store: image: your-skill-store:latest container_name: skill-store volumes: - ./data/skills:/data/skills web-ui: image: your-agent-ui:latest container_name: agent-web-ui ports: - 8080:80 environment: - ORCHESTRATOR_URLhttp://orchestrator:8000 api-server: image: your-api-server:latest container_name: agent-api-server ports: - 8088:8088 environment: - ORCHESTRATOR_URLhttp://orchestrator:8000启动命令# 在项目根目录执行 docker compose up -d # 查看服务状态 docker compose ps # 查看编排层日志 docker compose logs -f orchestrator启动后访问 http://127.0.0.1:8080 打开 WebUI访问 http://127.0.0.1:8088 访问 API 服务。4.2 命令行启动如果不用 Docker也可以直接用 Python 命令启动。# 安装依赖实际包名按项目要求改 pip install -r requirements.txt # 启动编排服务 python -m orchestrator.server --port 8000 # 启动 API 服务 python -m api.server --port 8088 # 启动 WebUI python -m webui.server --port 8080这种方式的优点是调试方便缺点是沙箱隔离不好做因为所有 Agent 直接跑在主系统上。建议只在开发环境这样用生产环境严格走 Docker。4.3 Skill 目录准备Skill 是这个系统里可复用的能力单元。目录结构一般是这样skills/ ├── code-reviewer/ │ ├── SKILL.md │ ├── directives/ │ │ └── safety.md │ └── techniques/ │ ├── check_security.py │ └── analyze_complexity.py ├──># 验证沙箱限制直接在 Agent Task 里让模型执行以下命令 ls /如果返回结果只有沙箱内的基础目录而不是宿主机的/etc、/home、/var等说明隔离生效。5.3 Skill 加载与自进化测试Skill 自进化是这个系统最有差异性的功能。测试方式先给 Agent 一个没有命中 Skill 的任务让它自由推理完成。完成后再给一个相同类型的任务观察系统是否尝试调用已沉淀的流程。检查 skill-store 的索引里是否有新增记录。举一个具体的场景任务把 data.csv 按月份汇总生成一个柱状图。如果系统里还不存在图表生成的 SkillAgent 会现场写代码完成。任务成功后系统会把这种任务的步骤抽象封装成一个 Skill。第二次再提交同类任务时Agent 应该直接调用 Skill而不是重新写代码。判断标准第二次任务耗时是否明显缩短。Skill 索引中是否新增了对应条目。Skill 内容是否覆盖了任务的关键步骤。5.4 人工介入测试人工介入机制解决了 Agent 不可完全信任的问题。测试方式配置一个需要审批的任务类型比如 delete 操作。让 Agent 执行时触发审批节点。在 WebUI 中查看待审批列表。批准任务后Agent 继续执行。拒绝任务Agent 停止执行。{ task: 删除 output/ 目录下所有临时文件, require_human_approval: true, approval_reason: 涉及批量文件删除需要人工确认 }预期结果任务挂起等待审批。批准后 Agent 才执行删除命令。5.5 批量任务测试批量任务能力决定了这套系统能不能用于生产线。测试方式准备一个目录里面放多份待处理文件。tasks/ ├── case1.csv ├── case2.csv ├── case3.csv └── case4.csv通过 API 或任务队列提交批量处理请求。观察系统是否按队列逐个执行。# 通过 API 触发批量任务 curl -X POST http://127.0.0.1:8088/api/tasks/batch \ -H Content-Type: application/json \ -d { task_type: data-analysis, input_dir: ./data/tasks, output_dir: ./data/results, agents: [data-analyzer] }预期结果队列中的任务逐个被执行结果写入 output 目录每个任务有独立日志。6. 接口 API 与批量任务API 服务是整个系统对外提供能力的关键入口。企业要把 Agent 能力集成到现有系统通常不会直接用 WebUI而是调用 API。6.1 任务提交接口典型请求curl -X POST http://127.0.0.1:8088/api/tasks \ -H Content-Type: application/json \ -d { task_id: task-20250101-001, description: 分析项目代码输出质量报告, agents: [code-reviewer, document-writer], sandbox: { type: docker, network: none, memory_limit: 2g }, options: { require_human_approval: false, max_iterations: 10 } }Python 调用示例import requests url http://127.0.0.1:8088/api/tasks payload { task_id: task-20250101-002, description: 汇总 data 目录下的日志生成错误报告, agents: [log-analyzer], sandbox: { type: docker, network: none } } response requests.post(url, jsonpayload, timeout30) print(response.json())6.2 任务状态查询任务提交后通过任务 ID 查询执行状态。curl http://127.0.0.1:8088/api/tasks/task-20250101-001返回内容一般包含状态、当前步骤、Agent 名称、日志摘要。6.3 批量任务队列设计批量任务的核心是把多个任务放入队列由调度器逐个执行。建议的队列设计{ queue_name: batch-analysis, concurrency: 2, tasks: [ {task_id: batch-001, input: ./data/file1.csv}, {task_id: batch-002, input: ./data/file2.csv}, {task_id: batch-003, input: ./data/file3.csv} ], retry: { max_retries: 3, backoff_seconds: 10 } }批量任务要特别注意失败重试。建议把任务拆成可重入的单元每个任务执行前记录开始状态执行后记录结果失败时根据状态决定是从头重跑还是从断点继续。7. 资源占用与性能观察这一节讲怎么观察系统资源帮助你在实际部署时判断配置是否够用。7.1 显存与内存观察如果你接的是本地大模型显存是主要瓶颈。观察命令# 查看 GPU 使用情况 nvidia-smi -l 2 # 查看模型服务进程显存占用 nvidia-smi --query-compute-appspid,used_memory --formatcsv更稳妥的判断是多 Agent 并发任务越多模型推理被调用越频繁显存占用会随之升高。如果并发量大建议考虑共享推理服务配合请求队列而不是让每个 Agent 各自占用一套模型。CPU 推理的差异在于延迟高但显存无压力。如果只是在开发环境验证流程CPU 加小模型也够用。生产环境对响应速度有要求再考虑 GPU。7.2 沙箱资源限制Docker 沙箱可以限制 CPU、内存和网络。这是控制整机资源占用最有效的手段。sandbox: type: docker resources: cpu_limit: 1.0 memory_limit: 2g network: none批量任务时如果并发沙箱过多即使模型没问题磁盘和内存也可能被打满。建议每个沙箱限制内存并设置并发上限。7.3 如何降低资源占用降低并发数比如同时只跑 2 个 Agent 任务。限制沙箱内存避免单个任务独占资源。优先使用小模型处理简单子任务大模型只用于核心推理。任务日志做轮转避免日志文件占满磁盘。8. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后 WebUI 打不开端口被占用或服务未启动检查 docker compose ps 和日志更换端口重启容器Agent 任务一直排队并发数设置过低或沙箱资源不足查看 orchestrator 日志和资源监控提高并发上限或减少并发任务沙箱创建失败Docker 套接字权限不足检查 /var/run/docker.sock 权限将运行用户加入 docker 组Agent 结果质量差模型能力不足或提示词不完整查看完整推理日志检查任务描述换更强模型优化任务描述Skill 未被自动调用Skill 索引未更新或 SKILL.md 描述不匹配检查 skill-store 日志查看索引手动重建索引优化 Skill 描述推理服务连接失败模型服务地址配置错误curl 测试模型接口确认 MODEL_API_BASE 和 MODEL_NAME批量任务中途失败单个文件格式异常或网络超时查看批量任务日志增加失败重试隔离异常文件人工审批未触发任务配置中没有设置审批节点检查任务 JSON 配置在 options 中设置 require_human_approval8.1 依赖安装失败如果 Python 依赖安装过程中出现编译错误优先检查 Python 版本是否匹配然后确认是否有系统级编译工具。Linux 环境可以检查 gcc 和 python3-dev 是否安装。不建议在依赖不完整的情况下强行运行环境问题会造成后续排错困难。8.2 模型文件缺失本地模型服务如果提示模型加载失败先确认模型文件目录是否存在以及文件名是否与配置一致。最好先单独启动模型服务通过接口测试确认推理正常再接入 Agent 编排层。8.3 显存不足如果 Agent 并发量大导致显存溢出优先降低并发数、减小上下文长度、限制沙箱数量。如果模型支持量化可以切换到更低精度的版本。8.4 端口冲突先确认当前端口被哪个进程占用# Linux / macOS lsof -i :8088 # Windows netstat -ano | findstr 8088确认后再决定换端口还是杀进程。9. 最佳实践与使用建议9.1 从小任务开始验证第一次跑通系统时不要直接上复杂流程。先提交一个单 Agent 简单任务确认链路通顺再做多 Agent 协作和批量任务。这样能区分问题出在编排层、模型层还是沙箱层。9.2 保留一套最小可运行配置把一套最小可运行配置固化成模板包括编排服务、推理服务地址、沙箱配置、基础 Skill。遇到无法排查的异常时用最小配置复现比从头检查整个系统效率高。9.3 目录结构统一管理建议按下面的方式组织目录data/ ├── tasks/ # 待处理任务 ├── results/ # 任务结果 ├── logs/ # 任务日志 ├── skills/ # Skill 目录 └── temp/ # 沙箱临时文件目录分离的好处是批量任务更方便审计更清晰。9.4 批量任务必须加日志和重试批量任务一旦跑起来中途失败是常态。每个任务都要记录状态流转失败时保留错误日志。重试策略建议用指数退避避免失败任务频繁重试打满资源。9.5 接口服务要限制访问API 服务如果暴露到内网要加认证和访问控制。最简单的做法是加 API Key 校验更严格的做法是绑定白名单 IP。9.6 合规与授权提醒再次强调如果 Agent 涉及用户数据、代码库、内部文档必须确认数据来源合法且有明确的授权和审计记录。涉及人脸、声音、版权素材的处理更要严格确认授权范围。沙箱解决了执行隔离问题不解决数据合规问题。10. 总结与下一步这个方向最值得尝试的点是把 Agent 从“能跑”推进到“可控地跑”。多 Agent 协同解决分工问题沙箱解决安全问题Skill 解决复用和进化问题人工介入解决信任问题。四者组合起来才是企业能接受的 Agent 工程化形态。最先验证的功能建议是沙箱隔离和 Skill 沉淀。沙箱能确认 Agent 不会越权执行Skill 能确认系统有持续学习能力。这两个功能跑通说明框架的安全底座和知识底座都成立。最容易踩的坑是Agent 编排看起来能跑但任务一多就出各种问题比如上下文溢出、并发资源竞争、Skill 调用不命中。解决思路不是堆更多参数而是建立日志和可观测性把每个任务的执行链路看清楚。后续可以扩展的方向包括把 Skill 的生成和审核做成闭环让 Agent 既能沉淀技能又能被人工审查接入更多类型的沙箱适配不同任务场景在批量任务之上叠加定时调度让 Agent 能按计划自动处理业务任务。建议收藏备用部署时遇到问题回来对照排查清单。
