How langtalks/swe-agent works
Project Type and Purpose
• This is an AI-powered multi-agent orchestration framework (not a web or mobile app).
• It automates software engineering tasks by splitting them into two distinct agents: the Architect Agent (research & planning) and the Developer Agent (implementation).
• It uses LangGraph to define and run the agent workflows, Anthropic Claude as the LLM, and a set of file- and code-analysis tools (tree-sitter, semantic search).
Key Architectural Components
• User Interface / Entry Point
• A CLI or API call that feeds the user’s request into LangGraph.
• LangGraph server (langgraph dev), configured by langgraph.json/langgraph_debug.py.
• LangGraph Orchestrator
• Defines two graphs (architect and developer) in langgraph.json.
• Routes messages/state between agents and manages sequencing.
• Main Agent Logic
• agent/graph.py – top-level orchestration of the two-stage workflow.
• Maintains AgentState with research scratchpad and eventual ImplementationPlan.
• Architect Agent
• Code in agent/architect/graph.py
• State model: SoftwareArchitectState (agent/architect/state.py).
• Uses prompt templates under agent/architect/prompts/ for hypothesis generation, research, and plan extraction.
• Invokes tools: search.py and codemap.py for codebase analysis.
• Developer Agent
• Code in agent/developer/graph.py
• State model: SoftwareDeveloperState (agent/developer/state.py).
• Uses prompt templates under agent/developer/prompts/ for diff generation and file writes.
• Invokes write.py to apply diffs to the file system.
• Shared Entities & State Models
• agent/common/entities.py – Pydantic models (ImplementationPlan, ImplementationTask, AtomicTask, DiffTask).
• Ensures type safety, validation, and clear data contracts between agents.
• Tools Layer
• File system operations (write.py)
• Code search (search.py)
• Code parsing/analysis (codemap.py leveraging tree-sitter)
• External Services
• Anthropic Claude Sonnet 4 LLM via LangChain
• Underlying Python environment with dependencies in pyproject.toml and locked by uv.lock
• .env file for API keys and configuration
Relationships and Data Flow
• User → LangGraph Orchestrator → Main Agent →
→ Architect Agent (LLM + search/codemap tools) → updates SoftwareArchitectState → outputs ImplementationPlan →
→ LangGraph routes ImplementationPlan to Developer Agent →
→ Developer Agent (LLM + write tool) → applies diffs to codebase → final results.
• All state transitions and messages are persisted in Pydantic models for traceability and resumability.
Architectural Patterns and Principles
• Separation of Concerns: Planning (Architect) vs. Execution (Developer).
• Atomic Tasks: Every change is broken into smallest diffable units.
• Stateful Workflows: Each agent holds its own state; orchestrator holds global state.
• Tool Integration: Agents never manipulate raw files directly—they call well-defined tools.
• Resumability & Traceability: Full scratchpad of messages and diffs persists between runs.