一、项目概述

The Agency是一个开源AI团队协作平台，在GitHub上7天获得10k星。它通过模拟工程师、设计师、增长营销、产品经理等多角色AI代理，实现复杂任务的自动化协作。本文将详细介绍其部署、配置和实际应用。

二、环境准备

2.1 系统要求

  • 操作系统：Linux/Windows/macOS（推荐Ubuntu 22.04+）
  • 内存：至少4GB RAM
  • 存储：20GB可用空间
  • Docker & Docker Compose

2.2 前置依赖安装

# 安装Docker
curl -fsSL https://get.docker.com | sh

# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker --version
docker-compose --version

2.3 Claude API准备

  1. 访问 Anthropic官网 注册账号
  2. 在控制台获取API密钥
  3. 记录密钥备用

三、快速部署

3.1 克隆项目

git clone https://github.com/the-agency/the-agency.git
cd the-agency

3.2 配置环境变量

cp .env.example .env
# 编辑.env文件，填入Claude API密钥
nano .env

3.3 Docker部署

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

3.4 访问控制台

浏览器打开：http://localhost:3000
默认账号：admin / admin123

image

四、架构解析

4.1 系统组件

4.1.1 前端服务（Port: 3000）

基于React的Web控制台，提供：

  • 任务提交界面
  • 进度监控面板
  • 角色管理配置
  • 历史记录查询
4.1.2 后端API服务（Port: 8080）

处理业务逻辑：

  • 任务调度分发
  • 代理状态管理
  • API路由处理
  • 数据库操作
4.1.3 代理引擎服务

每个角色独立运行：

  • 工程师代理（engineer）
  • 设计师代理（designer）
  • 增长营销代理（marketer）
  • 产品经理代理（product_manager）
4.1.4 数据库服务
  • PostgreSQL：存储任务数据
  • Redis：缓存和会话管理

4.2 数据流设计

用户提交任务 → API服务接收 → 任务解析 → 角色匹配
→ 代理执行 → Claude API调用 → 结果处理
→ 数据库存储 → 前端展示

4.3 配置文件说明

# agents/config.yaml
agents:
  engineer:
    enabled: true
    model: claude-3-sonnet-20240229
    max_tokens: 4000
    temperature: 0.7
    
  designer:
    enabled: true
    model: claude-3-opus-20240229
    max_tokens: 8000
    temperature: 0.8

五、核心功能实战

5.1 创建第一个任务

5.1.1 任务配置

在Web控制台点击"新建任务"，填写：

{
  "task_type": "web_application",
  "title": "开发待办事项应用",
  "description": "创建一个具有用户注册、登录、任务管理的待办事项Web应用",
  "tech_stack": ["React", "Node.js", "PostgreSQL"],
  "budget": 5000,
  "timeline": "2周"
}
5.1.2 角色分配

系统自动分配：

  • 产品经理：需求分析
  • 设计师：UI设计
  • 工程师：编码实现
  • 增长营销：推广方案
5.1.3 执行监控

在控制台实时查看：

  • 各角色进度
  • 任务状态
  • 生成的内容
  • 协作日志

5.2 工程师代理配置

5.2.1 技术栈设置
# engineer/config.yaml
tech_stacks:
  frontend:
    - React 18
    - TypeScript
    - Tailwind CSS
  backend:
    - Node.js 20
    - Express
    - Prisma ORM
  database:
    - PostgreSQL 15
  devops:
    - Docker
    - GitHub Actions
5.2.2 代码规范
// 代码生成规则
const codingRules = {
  naming: {
    variables: 'camelCase',
    functions: 'camelCase',
    classes: 'PascalCase',
    constants: 'UPPER_SNAKE_CASE'
  },
  style: {
    indent: 2,
    quotes: 'single',
    semicolons: true
  },
  quality: {
    maxFunctionLength: 30,
    maxFileLength: 300,
    commentRatio: 0.2
  }
};

5.3 设计师代理配置

5.3.1 设计系统
# designer/config.yaml
design_system:
  colors:
    primary: '#3b82f6'
    secondary: '#10b981'
    accent: '#8b5cf6'
  typography:
    font_family: 'Inter, sans-serif'
    scale: 1.25
  spacing:
    base: 4
    scale: [0, 4, 8, 16, 32, 64]
  components:
    button: true
    card: true
    form: true
    navigation: true
5.3.2 Figma集成
# 配置Figma API
export FIGMA_API_TOKEN=your_token
export FIGMA_FILE_ID=your_file_id

image

六、高级配置

6.1 自定义角色代理

6.1.1 创建新角色
# agents/custom_agent.py
class QAEngineerAgent:
    def __init__(self, config):
        self.config = config
        self.model = "claude-3-sonnet"
    
    def generate_test_cases(self, requirements):
        prompt = f"""
        基于以下需求生成测试用例：
        {requirements}
        
        包括：
        1. 功能测试用例
        2. 性能测试用例  
        3. 安全测试用例
        4. 兼容性测试用例
        """
        return self.call_claude(prompt)
    
    def call_claude(self, prompt):
        # API调用逻辑
        pass
6.1.2 注册到系统
# config.yaml
agents:
  qa_engineer:
    class: "agents.custom_agent.QAEngineerAgent"
    enabled: true
    config:
      test_framework: "pytest"
      coverage_target: 80

6.2 工作流定制

6.2.1 顺序工作流
workflow:
  name: "standard_dev"
  steps:
    - agent: "product_manager"
      action: "requirements_analysis"
    - agent: "designer" 
      action: "ui_design"
      depends_on: ["product_manager"]
    - agent: "engineer"
      action: "coding"
      depends_on: ["designer"]
    - agent: "qa_engineer"
      action: "testing"
      depends_on: ["engineer"]
6.2.2 并行工作流
workflow:
  name: "fast_track"
  steps:
    - agent: "product_manager"
      action: "requirements_analysis"
    - agent: ["designer", "engineer"]
      action: ["ui_design", "backend_dev"]
      depends_on: ["product_manager"]
      parallel: true

6.3 模型替换配置

6.3.1 使用OpenAI GPT
model_config:
  provider: "openai"
  model: "gpt-4-turbo"
  api_key: "${OPENAI_API_KEY}"
  parameters:
    temperature: 0.7
    max_tokens: 4000
6.3.2 使用本地模型
model_config:
  provider: "local"
  endpoint: "http://localhost:8080/v1/completions"
  model: "llama-3-70b"
  parameters:
    temperature: 0.8
    max_tokens: 8000

七、实战案例

7.1 案例一：电商网站开发

7.1.1 需求分析
项目：B2C电商平台
功能：商品展示、购物车、支付、订单管理
技术栈：Next.js、NestJS、PostgreSQL、Redis
时间：3周
7.1.2 执行过程
  1. 产品经理代理：输出PRD文档、用户故事、优先级
  2. 设计师代理：生成Figma设计稿、组件库、响应式方案
  3. 工程师代理：生成前后端代码、数据库设计、API文档
  4. 增长营销代理：SEO方案、营销文案、推广策略
7.1.3 成果产出
  • 完整的需求文档（50页）
  • Figma设计稿（20个页面）
  • 前后端代码（5000+行）
  • 部署配置（Docker、CI/CD）
  • 营销方案（关键词列表、内容日历）

7.2 案例二：内部工具开发

7.2.1 需求说明
项目：数据报表生成工具
功能：数据导入、模板配置、报表生成、导出
集成：MySQL、Excel、PDF生成
时间：1周
7.2.2 关键配置
task:
  type: "internal_tool"
  priority: "high"
  integrations:
    - mysql
    - excel
    - pdf_generator
  quality_gates:
    unit_test_coverage: 70
    e2e_test_passed: true
    security_scan: clean

7.3 案例三：内容营销自动化

7.3.1 工作流设计
触发：每周一上午9点
→ 增长营销代理分析热点话题
→ 产品经理代理确定内容方向
→ 工程师代理收集技术资料
→ 设计师代理制作视觉素材
→ 自动发布到社交媒体
7.3.2 效率对比
传统方式：人工团队（5人×8小时）= 40人时
The Agency：AI团队（自动执行）= 2人时（监控）
效率提升：20倍

image

八、性能优化

8.1 系统调优

8.1.1 Docker资源限制
# docker-compose.override.yml
services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G
8.1.2 数据库优化
-- 创建索引
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_created ON tasks(created_at);

-- 分区表（大量数据时）
CREATE TABLE tasks_2024 PARTITION OF tasks
FOR VALUES FROM ('2024-01-01') TO ('2024-12-31');

8.2 缓存策略

8.2.1 Redis配置
cache:
  enabled: true
  ttl: 3600  # 1小时
  max_memory: 1gb
  policy: allkeys-lru
8.2.2 缓存键设计
def get_cache_key(task_id, agent_type):
    return f"task:{task_id}:agent:{agent_type}:result"

8.3 监控告警

8.3.1 Prometheus指标
metrics:
  enabled: true
  port: 9090
  scrape_interval: 15s
  alerts:
    - name: high_error_rate
      expr: rate(http_requests_total{status="500"}[5m]) > 0.05
      for: 2m
8.3.2 日志收集
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"
  level: "info"

九、故障排除

9.1 常见问题

问题1：服务启动失败
错误：端口被占用
解决：检查端口占用情况
lsof -i :3000
kill -9 <PID>
问题2：Claude API调用失败
错误：Rate limit exceeded
解决：降低请求频率，配置重试策略
问题3：数据库连接失败
错误：Connection refused
解决：检查PostgreSQL服务状态
sudo systemctl status postgresql

9.2 调试工具

9.2.1 容器调试
# 进入容器
docker exec -it the-agency-backend bash

# 查看日志
docker logs the-agency-backend --tail 100 -f

# 容器资源使用
docker stats
9.2.2 API调试
# 测试API端点
curl -X GET http://localhost:8080/health
curl -X POST http://localhost:8080/tasks -d @task.json

十、最佳实践

10.1 开发规范

  1. 代码版本控制：所有配置和自定义代码提交到Git
  2. 环境分离：开发、测试、生产环境独立配置
  3. 文档完善：为自定义角色和工作流编写文档
  4. 测试覆盖：核心功能编写单元测试

10.2 安全建议

  1. API密钥管理：使用密钥管理服务，不在代码中硬编码
  2. 访问控制：配置防火墙，限制访问IP
  3. 数据加密：敏感数据加密存储
  4. 定期审计：检查系统日志和安全事件

10.3 成本优化

  1. 模型选择：根据任务复杂度选择合适的模型
  2. 请求优化：合并请求，减少API调用次数
  3. 缓存利用：合理使用缓存减少重复计算
  4. 资源调度：根据负载动态调整资源

十一、总结

The Agency作为开源AI团队平台，为开发者提供了强大的多角色协作能力。通过本文的实战指南，你可以：

  1. 快速部署：30分钟内搭建完整环境
  2. 灵活配置：根据需求定制角色和工作流
  3. 高效应用：在多个场景中提升开发效率
  4. 持续优化：监控和调优系统性能

建议从简单项目开始，逐步探索复杂场景。随着对系统的深入理解，你可以开发自定义角色，集成更多工具，打造适合自己团队的AI协作平台。

项目仍在快速发展中，关注GitHub仓库获取最新更新。社区活跃，遇到问题可以在Issues中寻求帮助。

下一步行动建议：

  1. 部署体验版，创建第一个任务
  2. 尝试修改配置，了解系统工作机制
  3. 开发一个简单自定义角色
  4. 在实际项目中应用，收集反馈优化

The Agency不仅是一个工具，更是探索AI团队协作未来方向的平台。期待看到你的创新应用！

# 开源 # 人工智能 # 运维
Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

cover

MateClaw 2.0 正式发布：从“一个能干活的人”到“一支能协作的队伍”

avatar MCP技术社区

SkillDock：Skills 管理、MCP 管理与插件管理实践

以 SkillDock 为例，讲解 macOS 与 Windows 多工具环境下的 Skills 管理、MCP 管理、插件管理和 Git 变更处理实践。

avatar MCP技术社区
cover

MCP更新： 2026-07-28：从 Agent 插件协议到企业 AI 工具总线

avatar MCP技术社区