ImplementationPlan, ImplementationTask, and AtomicTask in SWE-Agent: Purpose and Architecture

ImplementationPlan, ImplementationTask, and AtomicTask are hierarchical Pydantic models in the SWE-Agent framework that decompose high-level software engineering goals into executable file-level edits and atomic diff operations.

The SWE-Agent repository uses these three entities defined in agent/common/entities.py to bridge the gap between LLM planning and concrete code execution. By structuring implementation details into a rigid three-tier hierarchy, the framework enables the Architect agent to produce validated plans that the Developer agent can consume and execute deterministically.

The Three-Tier Hierarchy

SWE-Agent models code changes as a stack of increasing specificity, mirroring how engineers decompose project requirements into file modifications and individual edits.

AtomicTask – The Unit of Execution

The AtomicTask class represents the smallest indivisible operation in the system: a single instruction that generates one diff edit in a target file. Defined at [lines 4–8 of agent/common/entities.py](https://github.com/langtalks/swe-agent/blob/main/agent/common/entities.py#L4-L8), this model captures both the instruction and any research context required to perform it correctly.

Key fields include:

• atomic_task – The literal string instruction (e.g., "Add type hint Dict[str, Any] to function signature").
• additional_context – Supporting details gathered during the research phase, such as dependency constraints or style guidelines.

ImplementationTask – File-Level Grouping

ImplementationTask aggregates all atomic edits targeting a single file and describes the logical objective for that file. According to the source in [agent/common/entities.py (lines 9–14)](https://github.com/langtalks/swe-agent/blob/main/agent/common/entities.py#L9-L14), this model links the high-level plan to concrete operations.

Core attributes:

• file_path – The relative path to the file being modified.
• logical_task – A human-readable description of what the file change accomplishes (e.g., "Refactor authentication logic to use JWT tokens").
• atomic_tasks – A List[AtomicTask] containing the ordered sequence of edits to apply.

ImplementationPlan – The Strategic Blueprint

At the top of the hierarchy, ImplementationPlan acts as the container for all file-level tasks. As implemented at [lines 15–18 of agent/common/entities.py](https://github.com/langtalks/swe-agent/blob/main/agent/common/entities.py#L15-L18), this model is the primary interface between the planning and execution phases of the agent graph.

The sole required field is:

• tasks – A List[ImplementationTask] representing the complete, ordered set of modifications needed to fulfill the original requirement.

Integration with Agent Workflows

These entities orchestrate the handoff between SWE-Agent’s specialized agents, ensuring type-safe communication across the system.

Architect Agent Generation

The Architect agent instantiates these structures during the planning phase. In [agent/architect/graph.py (line 39)](https://github.com/langtalks/swe-agent/blob/main/agent/architect/graph.py#L39), the pipeline chains a JsonOutputParser(pydantic_object=ImplementationPlan) to the LLM output, automatically validating that the model’s response conforms to the expected schema before converting it into Python objects.

Developer Agent Consumption

The Developer agent retrieves the plan from its persistent state to drive execution. The DeveloperState class declared in [agent/developer/state.py (line 31)](https://github.com/langtalks/swe-agent/blob/main/agent/developer/state.py#L31) stores the plan as implementation_plan: Optional[ImplementationPlan], allowing the agent to iterate through tasks and submit each AtomicTask to the write tool.

Practical Code Examples

Manually Constructing a Plan

from agent.common.entities import AtomicTask, ImplementationTask, ImplementationPlan

# Define the smallest unit of work

atomic = AtomicTask(
    atomic_task="Add error handling for FileNotFoundError in load_config()",
    additional_context="Use try/except block and log error using logging.error"
)

# Group into a file-specific task

task = ImplementationTask(
    file_path="src/config.py",
    logical_task="Improve robustness of configuration loading",
    atomic_tasks=[atomic]
)

# Encapsulate in the top-level plan

plan = ImplementationPlan(tasks=[task])

Parsing LLM Output into Typed Objects

from agent.common.entities import ImplementationPlan
from langchain.output_parsers import JsonOutputParser

# Raw JSON returned by the LLM

plan_dict = {
    "tasks": [
        {
            "file_path": "api/routes.py",
            "logical_task": "Add pagination to user list endpoint",
            "atomic_tasks": [
                {
                    "atomic_task": "Add skip and limit parameters to get_users()",
                    "additional_context": "Use Query parameters with ge=0 for validation"
                },
                {
                    "atomic_task": "Apply slicing to the database query result",
                    "additional_context": "Use SQLAlchemy offset and limit"
                }
            ]
        }
    ]
}

# Validate and instantiate

plan = ImplementationPlan(**plan_dict)

Iterating Through the Plan During Execution

from agent.developer.state import DeveloperState

state = DeveloperState(implementation_plan=plan)

for impl_task in state.implementation_plan.tasks:
    print(f"Editing {impl_task.file_path}: {impl_task.logical_task}")
    for atomic in impl_task.atomic_tasks:
        # Typically submitted to the write tool here

        print(f"  Applying: {atomic.atomic_task}")

Summary

• AtomicTask represents a single, indivisible code edit instruction with supporting context, defined in [agent/common/entities.py](https://github.com/langtalks/swe-agent/blob/main/agent/common/entities.py).
• ImplementationTask groups atomic edits by target file, providing a logical description of the file-level objective and an ordered list of operations.
• ImplementationPlan serves as the top-level container that sequences all file tasks, acting as the validated contract between the Architect and Developer agents.
• These Pydantic models enable type-safe LLM output parsing via JsonOutputParser and maintain execution state in [agent/developer/state.py](https://github.com/langtalks/swe-agent/blob/main/agent/developer/state.py).

Frequently Asked Questions

How does the Architect agent ensure the LLM produces valid ImplementationPlan JSON?

The Architect pipeline in [agent/architect/graph.py](https://github.com/langtalks/swe-agent/blob/main/agent/architect/graph.py) uses LangChain’s JsonOutputParser configured with pydantic_object=ImplementationPlan. This parser validates the LLM’s raw output against the Pydantic schema before instantiation, raising validation errors if required fields like file_path or atomic_task are missing or malformed.

Can an ImplementationTask span multiple files?

No, the architecture enforces a strict one-file-per-task boundary. The file_path field in ImplementationTask is a string, not a list, ensuring that atomic tasks within a single implementation task all target the same file. Cross-file modifications require separate ImplementationTask entries within the ImplementationPlan.tasks list.

What happens if an AtomicTask fails during execution?

The Developer agent iterates sequentially through atomic_tasks. When a task fails (e.g., due to a merge conflict or syntax error), the agent can trap the exception, optionally append error details to atomic.additional_context, and either retry the specific edit or escalate to the Architect for replanning, all while maintaining the hierarchical structure of the original plan.

Why are these entities defined as Pydantic models rather than TypedDict?

Pydantic provides runtime validation, automatic JSON serialization, and schema generation that integrates with LangChain’s output parsers. This ensures that LLM responses conform to the expected structure before reaching the execution layer, preventing runtime errors from malformed JSON and enabling static analysis during framework development.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}