Implementing Plan-and-Execute Agents

For tasks requiring dynamic, step-by-step adjustments, one common approach is the ReAct pattern. However, some problems benefit from a more structured, forward-looking approach. An alternative architecture is the plan-and-execute agent. Instead of iterating through a tight thought-action-observation loop for every step, this agent first formulates a complete, multi-step plan and then executes it sequentially.

This separation of planning from execution is effective for tasks where the sequence of actions is largely predictable and doesn't depend on highly variable outcomes at each step.

The Anatomy of a Plan-and-Execute Agent

The architecture consists of two distinct phases:

1. Planning Phase: A dedicated Planner component, powered by an LLM, receives the high-level goal. Its sole responsibility is to decompose this goal into a concrete, ordered list of steps. The output of this phase is a Plan object, which serves as a blueprint for the entire task.
2. Execution Phase: An Executor component iterates through the steps of the generated plan. For each step, it performs the required action. The executor can be a simple function-calling mechanism or even a ReAct agent tasked with accomplishing just that single step.

This workflow ensures that the agent has a clear path forward before it begins, reducing the risk of getting sidetracked.

The Plan-and-Execute workflow separates the task into a planning phase, where an LLM generates a sequence of steps, and an execution phase, where an agent carries out each step in order.

Creating and Executing a Plan

The agent module provides tools for both planning and execution. The Planner class uses an LLM to generate a Plan object from a given goal.

For instance, we can set up a planner that uses a mock LLM to generate steps. In a real application, the llm_func would call a powerful model like GPT-4 or Claude 3.

from kerb.agent.planning import Planner, Plan

def planner_llm(prompt: str) -> str:
    """A mock LLM that generates a plan."""
    if "data analysis" in prompt.lower():
        return """1. Load the dataset from the source.
2. Clean and preprocess the data.
3. Perform exploratory data analysis (EDA).
4. Generate visualizations and a summary report."""
    return "1. Step A\n2. Step B"

# Create a planner with our LLM function
planner = Planner(llm_func=planner_llm)

# Generate a plan for a high-level goal
goal = "Create a data analysis pipeline"
generated_plan = planner.create_plan(goal)

print(f"Goal: {generated_plan.goal}")
print("\nGenerated Steps:")
for i, step in enumerate(generated_plan.steps, 1):
    print(f"  {i}. {step}")

The PlanAndExecuteAgent class abstracts this entire workflow. You provide it with an LLM function for planning, and it orchestrates both the creation of the plan and the execution of each step.

Here is a complete example of a PlanAndExecuteAgent that first devises a plan to analyze customer feedback and then executes it.

"""08_agent_planning.py"""

from kerb.agent.patterns import PlanAndExecuteAgent

def planner_llm(prompt: str) -> str:
    """LLM for planning."""
    if "plan" in prompt.lower() or "analyze customer feedback" in prompt.lower():
        return """1. Research the topic of sentiment analysis.
2. Analyze the feedback for main themes.
3. Write a summary of the findings.
4. Review and finalize the report."""
    return "Creating plan..."

def main():
    """Run agent planning example."""

    print("="*80)
    print("PLAN-AND-EXECUTE AGENT EXAMPLE")
    print("="*80)

    # Create the agent
    pae_agent = PlanAndExecuteAgent(
        name="PlanExecuteAgent",
        llm_func=planner_llm,
        max_iterations=5
    )

    goal = "Analyze customer feedback"
    print(f"\nGoal: {goal}")
    print(f"\nAgent: {pae_agent.name}")
    print("\nRunning Plan-and-Execute agent...")
    print("-"*80)

    result = pae_agent.run(goal)

    print(f"\nRESULTS:")
    print("-"*80)
    print(f"Status: {result.status.value}")
    print(f"Steps taken: {len(result.steps)}")
    print(f"Output: {result.output[:100]}...")

    # Show execution flow, highlighting the planning step
    print("\nExecution Flow:")
    print("-"*80)
    for i, step in enumerate(result.steps, 1):
        print(f"\n[{i}] ", end="")
        if step.thought:
            # The first thought is typically the plan itself
            print(f"Thought:\n{step.thought}")
        if step.action:
            print(f"    Action: {step.action}")

if __name__ == "__main__":
    main()

The first step of the agent's execution typically involves a "thought" that lays out the entire plan. Subsequent steps then focus on executing each part of that plan.

Handling Failures with Replanning

A critical challenge for plan-and-execute agents is their rigidity. If an early step fails or the environment changes unexpectedly, the original plan may become invalid. An implementation must include a mechanism for replanning.

Replanning involves:

1. Detecting a failure during the execution of a step.
2. Capturing the observation or error message from the failed step.
3. Feeding the original goal, the failed plan, and the error back to the Planner.
4. Generating a new, revised plan that accounts for the failure.

For example, if a plan to "Deploy application to production" fails at the "Run tests" step due to a build error, a replanning loop would generate a new plan like:

1. Debug build issues.
2. Fix errors in the codebase.
3. Re-run tests.
4. Build the application.
5. Deploy to production.

While PlanAndExecuteAgent provides a high-level orchestration, you can implement custom replanning logic by building a loop around a Planner and an executor. The kerb.agent.planning.replan function provides utilities to facilitate this process.

When to Use Plan-and-Execute Agents

This architecture is not a universal replacement for ReAct. Each pattern has its strengths.

Choose a Plan-and-Execute agent when:

• The task is complex and requires foresight. Decomposing a large problem upfront is beneficial.
• The steps are mostly predictable. The environment is stable, and the outcome of one step doesn't drastically change the next.
• An inspectable plan is valuable. The generated plan itself can be reviewed by a human or used for progress tracking.
• You want to minimize iterative LLM calls. A single, comprehensive planning call may be more efficient than multiple small calls in a ReAct loop.

Stick with a ReAct agent when:

• The task is exploratory. The agent needs to react to new information at each step.
• The environment is highly dynamic. The agent must constantly adapt its strategy.
• Immediate feedback is necessary. The thought-action-observation loop provides tight feedback for quick corrections.

For example, generating a research report is a great fit for a plan-and-execute agent (research, outline, draft, review). In contrast, browsing the web to find an answer to a complex question is better suited for a ReAct agent, as it needs to react to search results at each step.