使用 LangGraph 的软件工程代理 - 由 LangTalks 提供

一款基于人工智能的先进软件工程代理，通过智能规划与执行自动化代码实现。采用 LangGraph 构建，确保多代理工作流的可靠性。

⚠️ Alpha 状态：本项目正处于积极开发中。功能可能会发生变化，部分功能仍处于实验阶段。非常适合希望参与塑造 AI 驱动开发未来的早期采用者和贡献者。

端到端展示

🚀 功能特性

• 智能代码规划：AI 架构师分析需求并创建详细的实施方案
• 自动化代码生成：开发者代理根据计划精确地进行文件修改
• 多代理工作流：分离规划与实施阶段，提升可靠性
• 代码库理解：利用 tree-sitter 和语义搜索进行高级代码分析
• 增量式开发：将任务分解为原子级，使更改更安全、更易管理

🏗️ 架构设计

系统采用两阶段的 LangGraph 工作流：

1. 架构师代理 - 研究与规划

架构师代理负责：

• 研究代码库结构与模式
• 分析需求并提出假设
• 生成包含原子任务的详细实施方案
• 利用工具进行代码搜索和语义理解

2. 开发者代理 - 实施

开发者代理负责：

• 按步骤执行实施方案
• 精确地进行原子级别的代码修改
• 创建新文件或修改现有文件
• 根据原始需求验证更改结果

工作流概述

用户请求 → 架构师（研究与规划）→ 开发者（实施）→ 结果

关键组件：

• 状态管理：使用 Pydantic 模型在各代理间实现结构化的数据流转
• 工具集成：文件系统操作、代码搜索及结构分析
• 研究流程：基于假设驱动的代码库探索
• 原子级执行：细粒度任务确保可靠的实施过程

🔄 代理状态管理

系统采用分层的状态管理方法，借助 Pydantic 模型实现类型安全与验证。每个代理维护自己的状态，同时共享公共实体以实现无缝的数据流动。

主代理状态 (AgentState)

顶层协调器状态，用于管理整个工作流：

class AgentState(BaseModel):
    implementation_research_scratchpad: Annotated[list[AnyMessage], add_messages]
    implementation_plan: Optional[ImplementationPlan] = None

字段：

• implementation_research_scratchpad：研究与规划阶段的消息记录
• implementation_plan：由架构师代理创建的待开发者执行的结构化方案

架构师代理状态 (SoftwareArchitectState)

管理基于假设驱动的研究与规划阶段：

class SoftwareArchitectState(BaseModel):
    research_next_step: Optional[str] = None
    implementation_plan: Optional[ImplementationPlan] = 0  
    implementation_research_scratchpad: Annotated[list[AnyMessage], add_messages] = []
    is_valid_research_step: Optional[bool] = None

字段：

• research_next_step：当前正在探索的假设或研究方向
• implementation_plan：生成的包含原子任务的结构化方案
• implementation_research_scratchpad：研究对话历史及工具输出
• is_valid_research_step：用于验证研究假设质量的标志位

工作流：

1. 生成研究假设 → 验证假设 → 进行研究 → 提取实施方案

开发者代理状态 (SoftwareDeveloperState)

负责逐步执行架构师的方案：

class SoftwareDeveloperState(BaseModel):
    implementation_plan: Optional[ImplementationPlan] = None
    current_task_idx: Optional[int] = 0
    current_atomic_task_idx: Optional[int] = 0
    diffs: Optional[Diffs] = None
    atomic_implementation_research: Annotated[list[AnyMessage], add_messages_with_clear]
    codebase_structure: Optional[str] = None
    current_file_content: Optional[str] = None

字段：

• implementation_plan：从架构师代理接收到的方案
• current_task_idx：当前正在实施的文件级任务索引
• current_atomic_task_idx：该任务中的原子级变更索引
• diffs：用于精确文件修改的代码差异
• atomic_implementation_research：针对当前实施步骤的研究记录
• codebase_structure：目标代码库的当前结构快照
• current_file_content：正在修改的文件内容

工作流：

1. 遍历任务列表 → 针对具体实施进行研究 → 生成差异 → 应用更改

共享实体

这些 Pydantic 模型定义了各代理之间的数据契约：

ImplementationPlan

class ImplementationPlan(BaseModel):
    tasks: List[ImplementationTask]

顶层方案，包含所有文件级的实施任务。

ImplementationTask

class ImplementationTask(BaseModel):
    file_path: str                    # 待修改的目标文件
    logical_task: str                 # 更改的高层次描述
    atomic_tasks: List[AtomicTask]    # 细粒度的修改步骤

表示针对特定文件所需的更改。

AtomicTask

class AtomicTask(BaseModel):
    atomic_task: str            # 具体的代码修改指令
    additional_context: str     # 此次更改的研究背景

最小的实施单元——单个代码变更。

DiffTask（开发者专用）

class DiffTask(BaseModel):
    original_code_snippet: str    # 被替换的确切代码片段
    task_description: str         # 详细的变更说明

用于代码修改的精确差异指令。

状态流转示例

用户请求
    ↓
AgentState {research_scratchpad: [HumanMessage("添加认证功能")]}
    ↓
SoftwareArchitectState {
    research_next_step: "查找现有的认证模式",
    implementation_research_scratchpad: [research_messages...]
}
    ↓ （研究完成后）
SoftwareArchitectState {
    implementation_plan: ImplementationPlan([
        ImplementationTask(
            file_path: "auth.py",
            atomic_tasks: [AtomicTask("添加User模型")]
        )
    ])
}
    ↓
SoftwareDeveloperState {
    implementation_plan: <接收到的计划>,
    current_task_idx: 0,
    current_atomic_task_idx: 0,
    current_file_content: "# auth.py 的内容"
}
    ↓ （实现完成后）
最终结果：修改后的代码库

状态管理的优势

• 类型安全：通过 Pydantic 验证防止状态被破坏
• 可追溯性：完整的消息历史便于调试
• 可恢复性：状态可以持久化并恢复
• 模块化：每个代理管理自己的职责范围
• 原子性：细粒度的任务分解实现精确控制

📋 前置条件

• Python 3.12+
• uv（Python 包管理器）
• Anthropic API 密钥（Claude Sonnet 4）

⚡ 快速入门

1. 克隆仓库

git clone https://github.com/langtalks/swe-agent-langgraph.git
cd swe-agent-langgraph

2. 设置环境

# 使用 uv 安装依赖
uv sync

# 创建环境文件
cp .env.example .env.local
# 在 .env 中添加你的 Anthropic API 密钥和 langsmith 信息

3. 克隆一个仓库到 ./workspace_repo

git clone https://github.com/browser-use/browser-use ./workspace_repo

4. 运行代理

# 激活环境
source .venv/bin/activate

# 启动 LangGraph 服务器
langgraph dev

4. 示例用法 输入：

使 browser-use 代理能够接受多模态指令，支持图像输入（如 step1.png、step2.png）与文本一起使用。这将提高代理对模糊或不明确文本命令的理解和执行能力。

输出：（浏览工作区仓库的 git）

🛠️ 开发

项目结构

agent/
├── architect/          # 规划与研究代理
│   ├── graph.py       # 主架构师工作流
│   ├── state.py       # 状态定义
│   └── prompts/       # 提示模板
├── developer/          # 实现代理  
│   ├── graph.py       # 主开发者工作流
│   ├── state.py       # 状态定义
│   └── prompts/       # 提示模板
├── common/            # 共享实体和状态
│   └── entities.py    # Pydantic 模型
└── tools/             # 文件操作和搜索工具
    ├── search.py      # 代码搜索工具
    ├── codemap.py     # 代码分析工具
    └── write.py       # 文件操作工具

workspace_repo/        # 目标代码库
scripts/              # 工具脚本
helpers/              # 提示模板和实用工具
static/               # 文档图片

核心组件

实体与状态管理：

• ImplementationPlan：结构化的任务分解
• AtomicTask：单个代码修改单元
• ImplementationTask：文件级别的实现步骤

代理工作流：

• 基于研究的规划，并验证假设
• 使用工具辅助进行代码探索和分析
• 逐步实施并进行验证

运行测试

# 运行所有测试
uv run pytest

# 带覆盖率运行
uv run pytest --cov=agent

# 运行特定测试模块
uv run pytest tests/test_architect.py

📁 主目录文件

文件	描述
README.md	项目文档（本文档）
pyproject.toml	Python 项目配置及依赖
langgraph.json	LangGraph 应用程序配置及图定义
langgraph_debug.py	用于开发和测试的调试配置
uv.lock	锁定的依赖版本，确保构建可重复性
.env	环境变量（根据 .env.example 创建）
.env.example	环境配置模板
.gitignore	Git 忽略规则，用于 Python 和 IDE 文件
.python-version	pyenv 的 Python 版本规范

🎯 使用场景

• 功能开发：根据高层次需求实现新功能
• Bug 修复：分析并修复问题，自动完成代码更改
• 代码重构：在保持功能不变的情况下重组代码
• 文档编写：生成和更新代码文档
• 测试：创建测试用例并修复失败的测试

🗺️ 路线图 - LangTalks 社区项目！

我们正在共同构建 AI 驱动软件开发的未来！以下是接下来的主要功能，期待社区贡献：

🔄 核心代理增强

• 多步研究与开发循环：通过反馈循环迭代优化实施计划
• 测试代理：专门用于单元测试、功能测试和测试用例生成的代理
• 错误修复代理：专门用于检测、分析和修复代码错误的代理
• 产品经理代理：负责高层次规划和需求分析的代理

🔧 开发工具与质量

• 添加 linter 工具：将代码质量工具（ESLint、Black、Pylint）集成到工作流中
• 组件评估基准测试：性能指标和质量评估框架
• 代码语义索引：高级代码理解和相似度检测

🌐 集成与连接

• GitHub MCP 集成：直接与 GitHub 仓库和工作流集成
• Context7 MCP 集成：增强上下文管理和代码理解能力
• 多语言支持：从 Python 扩展到 JavaScript、TypeScript、Java、Go 等

📈 高级功能（未来）

• 交互式规划 UI：用于查看和修改计划的 Web 界面
• 协作工作流：多开发者协调与冲突解决
• 性能优化：加快研究和实施周期
• 插件系统：可扩展的工具和代理架构

想参与贡献吗？ 选择上述任意功能加入我们的 LangTalks 社区吧！每个功能都适合个人贡献者或小型团队完成。

🤝 贡献方式

我们欢迎任何形式的贡献！该项目旨在推动 AI 驱动软件开发的边界。我们需要帮助的领域包括：

优先领域

• 代理改进：更好的推理和规划策略
• 工具开发：新的代码分析和修改工具
• 测试：全面的测试覆盖和验证框架
• 文档：示例、教程和使用案例
• 性能：优化和基准测试

如何贡献

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 按照现有代码风格进行修改
4. 为新功能添加测试
5. 确保测试通过（uv run pytest）
6. 如有需要，更新文档
7. 提交更改（git commit -m '添加超赞功能'）
8. 推送到分支（git push origin feature/amazing-feature）
9. 打开带有清晰描述的 Pull Request

开发环境搭建

# 克隆你的 Fork
git clone https://github.com/langtalks/swe-agent-langgraph.git
cd swe-agent-langgraph

# 设置开发环境
uv sync --dev

# 安装 pre-commit 钩子（可选但推荐）
pre-commit install

# 运行测试以确保一切正常
uv run pytest

📊 技术细节

依赖项

• LangGraph: 多智能体工作流编排
• LangChain: AI 集成与工具管理
• Anthropic: Claude Sonnet 4 提供智能推理能力
• Tree-sitter: 强大的代码解析与分析工具
• Pydantic: 类型安全的数据验证与序列化

性能考量

• 原子化任务执行以保证可靠性
• 使用 tree-sitter 进行高效代码分析
• 结构化状态管理以提升可扩展性
• 基于工具的架构设计以增强可扩展性

🔧 配置

关键配置文件：

• langgraph.json: 定义智能体图及依赖关系
• .env: API 密钥及其他环境变量
• pyproject.toml: Python 依赖与项目元数据

📄 许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

🙏 致谢

• 基于 LangGraph 构建，提供可靠的任务流支持
• 由 Anthropic Claude 提供智能推理能力
• 使用 tree-sitter 实现稳健的代码解析
• 更多信息请参阅我们的 deepwiki

📞 支持与社区

• LangTalks 主页: 访问 www.langtalks.ai 获取社区资源与支持
• 问题: 通过 GitHub Issues 报告 bug 或请求功能
• 讨论: 加入 GitHub Discussions 参与交流
• 文档: 完整文档见本 README

---

准备好用 AI 彻底革新软件开发了吗？欢迎加入 LangTalks，共同构建自动化编码的未来！ ⚡🤖

SWE-Agent 快速上手指南

SWE-Agent 是一款基于 LangGraph 构建的高级 AI 软件工程代理，能够通过智能规划和执行自动化代码实现。它采用“架构师 + 开发者”的双代理工作流，将需求分析、代码规划与具体实施分离，以提高代码生成的准确性和可靠性。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本: 3.12 或更高版本
• 包管理器: uv (推荐的现代 Python 包管理器)
• API 密钥: Anthropic API Key (需支持 Claude Sonnet 模型)
• Git: 用于克隆目标代码库

注意：本项目目前处于 Alpha 阶段，功能可能随时变更，适合早期采用者和贡献者体验。

安装步骤

1. 克隆项目仓库

首先获取 SWE-Agent 的源代码：

git clone https://github.com/langtalks/swe-agent-langgraph.git
cd swe-agent-langgraph

2. 安装依赖

使用 uv 同步安装项目所需的所有依赖包：

uv sync

(国内用户若遇到网络问题，可尝试配置 uv 使用国内镜像源，例如：export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple)

3. 配置环境变量

创建本地环境配置文件并填入必要的 API 密钥：

cp .env.example .env.local

编辑 .env.local 文件，填入您的 Anthropic API Key 和 LangSmith 配置（如需）：

# .env.local 内容示例
ANTHROPIC_API_KEY=your_anthropic_api_key_here
LANGSMITH_API_KEY=your_langsmith_api_key_here # 可选
LANGSMITH_TRACING=true

4. 准备目标代码库

SWE-Agent 需要在一个具体的代码库中工作。创建一个工作目录并克隆您想要修改的项目（示例中使用 browser-use）：

git clone https://github.com/browser-use/browser-use ./workspace_repo

基本使用

1. 激活环境并启动服务

激活虚拟环境并启动 LangGraph 开发服务器：

source .venv/bin/activate
langgraph dev

启动成功后，终端会显示本地服务地址（通常为 http://localhost:8123），LangGraph Studio 界面将自动在浏览器中打开。

2. 提交任务

在 LangGraph Studio 界面中，输入您的需求指令。SWE-Agent 会自动协调“架构师”进行研究和规划，然后指挥“开发者”执行代码修改。

输入示例：

Enable the browser-use agent to accept multi-modal instructions by supporting image inputs (e.g., step1.png, step2.png) alongside text. This will improve the agent's ability to interpret and follow ambiguous or unclear textual commands.

3. 查看结果

代理执行完成后，您可以在界面中查看：

• Architect Agent 生成的详细实施计划。
• Developer Agent 生成的代码差异（Diffs）。
• 最终修改后的文件内容已自动应用到 ./workspace_repo 目录中。

您可以直接在本地 IDE 中检查 ./workspace_repo 下的代码变更，验证运行结果。