跳到主要内容
AI教程

IvyClaw 实战：构建具备规划、编码、测试与审查能力的多智能体研发系统

本文介绍 IvyClaw 的核心架构、环境配置、API 与异步任务启动方式，并通过工程化视角讲解多智能体协作、沙箱执行、持久化、人工审批、可观测性和生产部署。

AI我搜编辑部阅读约 14 分钟
IvyClaw 实战：构建具备规划、编码、测试与审查能力的多智能体研发系统

一、IvyClaw 是什么

IvyClaw 是一个面向软件研发任务的多智能体 AI Agent 工程系统，基于 DeepAgents 与 LangGraph 构建。它不只执行一次大模型调用，而是将需求理解、任务规划、资料检索、代码实现、自动测试、代码审查和结果返回组织成可持续运行的 Agent Workflow。

项目使用 Python、FastAPI、PostgreSQL、Redis、ARQ、Docker、Prometheus 和 Grafana 等技术，适合用于学习和实践 AI Agent 的工程化落地。

需要注意的是，仓库中部分能力仍属于工程原型或演示实现。若用于生产环境，还需要进一步完善身份认证、权限控制、安全隔离和基础设施配置。

项目地址：IvyClaw GitHub Repository。

二、核心工作流与系统架构

IvyClaw 将一次研发请求拆分为多个职责明确的 Agent。典型流程如下：

User Request
      ↓
   Gateway
      ↓
  Dispatcher
      ↓
   Planner
      ↓
Researcher（按需）
      ↓
    Coder
      ↓
   Tester
      ↓
  Reviewer
      ↓
Final Response

Planner 负责理解需求、规划任务并进行决策；Researcher 在需要时检索和整理资料；Coder 负责实现和修改代码；Tester 执行测试并定位问题；Reviewer 对最终结果进行代码审查。

请求通常先进入 API Gateway，再由渠道适配器和 Dispatcher 交给 Agent Runtime。PostgreSQL 负责持久化会话状态与 LangGraph Checkpointer、Store 数据，Redis 用于缓存、限流、运行时状态和任务队列。耗时任务则交给 ARQ Worker 异步执行。

三、准备运行环境

开始前，请准备 Python 项目运行环境、可用的 PostgreSQL 和 Redis 服务，以及符合项目配置要求的模型 API。项目使用 uv 管理 Python 依赖。

首先克隆仓库并进入项目目录：

git clone https://github.com/ivyfan-toowell/IvyClaw.git
cd IvyClaw

然后从示例文件创建本地环境配置。Linux、macOS 或类 Unix 环境可以执行：

cp .env.example .env

Windows PowerShell 可以执行：

Copy-Item .env.example .env

在 .env 中根据本地环境填写必要配置，例如：

IVC_API_KEY=your_api_key_here
IVC_POSTGRES_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_DATABASE_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_REDIS_URL=redis://localhost:6379/0

请不要把真实的 .env 文件提交到 GitHub。LLM API Key、LangSmith API Key、飞书 App Secret、数据库密码和真实网关 API Key 等敏感信息都应保存在本地或安全的部署环境中。

四、安装依赖并启动服务

安装 Python 依赖

在项目根目录执行：

uv sync

该命令会按照项目配置同步 Python 环境和依赖。

启动 FastAPI API

使用以下命令启动开发服务器：

uv run uvicorn api.app:app --reload --port 8000

启动后打开 http://localhost:8000/docs，即可查看 FastAPI 自动生成的 Swagger API 文档。

启动 ARQ Worker

如果需要处理耗时的 Agent 任务，还应在另一个终端启动 ARQ Worker：

uv run arq tasks.worker.WorkerSettings

请求可以通过 Redis 队列提交给 Worker，由 Worker 调用 Agent Runtime，并持久化任务结果。异步任务流程通常包含 Job ID、任务状态查询、后台执行、幂等提交和结果获取。

启动飞书长连接

需要使用飞书 WebSocket 接入时，可以执行：

uv run python -m channels.feishu_ws

IvyClaw 也支持飞书 Webhook、Generic Webhook 和 CLI 等入口。不同渠道会被统一转换为 InboundMessage，之后复用同一套 handle_message() 和 Agent 处理逻辑。

五、理解 Agent 的工具调用

IvyClaw 为不同 Agent 分配与职责匹配的最小工具集，减少不必要的调用和误操作风险。项目支持的工具类型包括：

  • Git：查看和操作代码版本。
  • pytest：执行自动化测试。
  • Python 与 Shell：运行开发命令。
  • Web Search：通过 Tavily 或 Exa 进行信息检索。
  • MCP：接入外部工具和服务。
  • File Tools：读取和修改工作区文件。
  • Sandbox：隔离执行 Agent 生成的代码。

项目还通过 skills/ 沉淀可复用的研发流程，包括需求澄清、系统化调试、测试驱动开发、单元测试以及完成前验证。典型目录包括：

skills/
├── fastapi-endpoint/
├── requirements-clarification/
├── systematic-debugging/
├── test-driven-development/
├── unit-test/
└── verification-before-completion/

六、代码沙箱与安全执行

Agent 生成的代码不会直接在主要服务进程中执行，而是可以放入隔离环境运行。IvyClaw 支持 Docker Sandbox 和 Daytona Sandbox，并支持 Python、pytest、Git 等命令执行。

沙箱能力包括独立工作目录、沙箱复用与生命周期管理，以及 CPU、Memory 和 PID 等资源限制。生产环境默认使用 Docker Sandbox，同时为 gVisor 或 Kata 等更强隔离运行时预留扩展空间。

在配置沙箱时，应结合实际风险评估网络权限、文件访问范围、资源上限和并发规模。README 明确指出，生产环境仍需进一步加强安全隔离，不应把当前演示配置直接视为完整的安全方案。

七、状态持久化与异步任务

持久化组件

PostgreSQL 主要保存 LangGraph Checkpointer、Store、会话状态和其他持久化数据；Redis 则承担缓存、限流、任务队列和运行时状态等职责。借助 Checkpointer 和 Store，Agent 执行上下文可以跨请求持续运行。

异步任务流程

对于执行时间较长的研发任务，推荐让 FastAPI 创建任务，再由 Redis 和 ARQ Worker 异步处理：

Client
  ↓
FastAPI
  ↓
Create Job
  ↓
Redis Queue
  ↓
ARQ Worker
  ↓
Agent Runtime
  ↓
Persist Result
  ↓
Query Job Status

这种方式可以避免长时间占用同步 HTTP 请求，并为任务状态查询、重试和结果持久化提供基础。

八、Human-in-the-Loop：为高风险操作加入审批

删除文件、执行破坏性修改等操作不适合完全自动化。IvyClaw 支持 Human-in-the-Loop，当 Agent 请求高风险工具调用时，可以中断执行并等待人工决策。

Agent requests risky action
          ↓
       Interrupt
          ↓
    Human Approval
       ↓       ↓
    Approve   Reject
       ↓
 Command(resume)
       ↓
Agent continues

人工批准后，通过恢复命令继续执行；如果拒绝，则终止或改变当前流程。该机制能在自动化效率与操作安全之间建立控制点。

九、网关、多租户与稳定性治理

请求进入 Agent Runtime 前，会经过网关层完成身份识别和基础治理。当前仓库提供的能力包括：

  • API Key 鉴权。
  • Tenant 识别与隔离。
  • Rate Limit 限流。
  • Idempotency 幂等控制。
  • Request Context 请求上下文。
  • Audit Log 操作审计。

README 特别说明，当前 Key 和 Tenant 主要作为演示配置。生产环境应接入数据库或专门的身份认证系统，并进一步完善租户权限和数据隔离。

基础设施层还提供 Retry、Timeout、Fallback、Concurrency Control、PostgreSQL Connection Pool、Redis Connection Pool 和 Sandbox Pool 等机制，用于应对高并发、模型异常和基础设施抖动。

十、可观测性、测试与评估

IvyClaw 集成了多种可观测组件。LangSmith 用于追踪 Agent 和 LLM 调用链，Prometheus 负责指标采集，Grafana 用于可视化监控，此外还提供结构化日志和审计日志。

运行时可以重点关注以下指标：

  • 请求延迟与错误率。
  • 并发量。
  • LLM 调用次数。
  • Token 使用量与成本。
  • ARQ Worker 状态。
  • Sandbox 状态。

项目还包含 tests/、eval/ 和 loadtest/ 目录，覆盖 pytest 自动化测试、Agent Runtime 测试、Code Cases、Execution Scorer、LLM Judge、Baseline Evaluation、Reviewer Flow Test 和 Locust 压测。

推荐按照“开发、自动化测试、Agent Evaluation、压力测试、指标观测、问题优化”的顺序建立验证闭环，而不是只通过一次人工对话判断 Agent 是否可靠。

十一、Docker 生产部署

如果需要启动完整服务栈，可以使用仓库提供的生产 Compose 配置：

docker compose -f docker-compose.prod.yml up -d --build

生产部署涉及 FastAPI Web 服务、ARQ Worker、飞书服务、PostgreSQL、Redis、Prometheus 和 Grafana。API 与 Worker 可以共同访问 Agent Runtime，Agent Runtime 则通过 Docker Sandbox 执行生成的代码。

正式上线前，应检查数据库和 Redis 连接、密钥管理、API 鉴权、租户隔离、限流策略、沙箱资源限制、日志审计以及监控告警配置。

十二、从项目结构定位代码

熟悉目录结构有助于快速扩展功能：

IvyClaw/
├── agent/          # 主 Agent 与任务调度
├── api/            # FastAPI API
├── channels/       # CLI / Feishu / Webhook 接入
├── gateway/        # API 鉴权、Tenant、限流
├── infra/          # PostgreSQL、Redis、LLM Router
├── middleware/     # 请求上下文、并发、审计、成本统计
├── obs/            # Metrics 与可观测性
├── profiles/       # 模型与 Agent Profile
├── sandbox/        # Docker / Daytona 沙箱
├── skills/         # Agent Skills
├── subagents/      # Planner / Researcher / Coder / Tester / Reviewer
├── tasks/          # ARQ 异步任务
├── tools/          # Git / pytest / Search / MCP 工具
├── eval/           # Agent Evaluation
├── loadtest/       # Locust 压测
├── tests/          # 自动化测试
├── scripts/        # 开发、测试与演示脚本
├── web/            # Web UI
├── Dockerfile
├── docker-compose.prod.yml
├── pyproject.toml
└── .env.example

十三、实战使用建议

  1. 先配置 .env、PostgreSQL 和 Redis，并确认 API 能通过 Swagger 文档访问。
  2. 先以同步 API 或 CLI 验证基础 Agent Workflow，再启动 ARQ Worker 处理长任务。
  3. 为 Coder、Tester 和 Reviewer 分别检查工具权限，避免给单个 Agent 分配不必要的高风险能力。
  4. 对生成代码启用沙箱执行，并为 CPU、内存、进程数和工作目录设置合理限制。
  5. 涉及删除或破坏性修改时启用 Human-in-the-Loop，不要默认自动批准。
  6. 通过 LangSmith、Prometheus、Grafana 和结构化日志观察请求链路、成本、延迟与错误。
  7. 上线前运行 pytest、Agent Evaluation 和 Locust 压测，并根据结果调整模型路由、并发和重试策略。

结语

IvyClaw 的重点不是单一模型调用，而是把多智能体协作、工具调用、代码沙箱、状态持久化、异步执行、人工审批、网关治理和可观测性组合成一套软件研发 Agent 工程系统。

完成本地启动后，可以从现有的 subagents/、tools/ 和 skills/ 入手，逐步理解 Planner、Researcher、Coder、Tester 与 Reviewer 的协作方式，再根据业务需求扩展渠道、工具或评估流程。