google__adk-docs/docs/agents/workflow-agents/loop-agents.md

Loop template workflow agent

Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.2.0

The LoopAgent class is a template workflow agent that executes its sub-agents in a loop for a specified number of iterations or until a termination condition is met. Use the LoopAgent when your workflow involves repetition or iterative refinement, such as revising code or a document. As with other templated workflows, the execution of a LoopAgent object is not controlled by an AI model, and is deterministic in how it executes its sub-agents. The sub-agents within the defined loop may or may not utilize AI models, but the overall execution of those sub-agents is ultimately managed by the LoopAgent object you define.

!!! note "Alternative: graph-based workflows"

Starting in ADK 2.0 for Python and Go, templated workflows have been superseded

by more flexible workflow structures, including
[graph-based workflows](/graphs/) and
[dynamic workflows](/graphs/dynamic/).

Example scenario

You want to build an agent that can generate images of food, but sometimes when you want to generate a specific number of items, such as bananas, the agent generates a different number of those items in the image, such as an image of 7 bananas. You have two tools: Generate Image, Count Food Items. If your goal is to keep generating images until it either correctly generates the specified number of items, or after a certain number of iterations, you can build your agent using a LoopAgent workflow.

How it Works

When the LoopAgent's Run Async method is called, it performs the following actions:

1. Sub-Agent Execution: It iterates through the Sub Agents list in order. For each sub-agent, it calls the agent's Run Async method.

2. Termination Check:

   Crucially, the LoopAgent itself does not inherently decide when to stop looping. You must implement a termination mechanism to prevent infinite loops. Common strategies include:

   • Max Iterations: Set a maximum number of iterations in the LoopAgent. The loop will terminate after that many iterations.
   • Escalation from sub-agent: Design one or more sub-agents to evaluate a condition (e.g., "Is the document quality good enough?", "Has a consensus been reached?"). If the condition is met, the sub-agent can signal termination (e.g., by raising a custom event, setting a flag in a shared context, or returning a specific value).

Full Example: Iterative Document Improvement

Imagine a scenario where you want to iteratively improve a document:

• Writer Agent: An LlmAgent that generates or refines a draft on a topic.

• Critic Agent: An LlmAgent that critiques the draft, identifying areas for improvement.

  LoopAgent(sub_agents=[WriterAgent, CriticAgent], max_iterations=5)
  

In this setup, the LoopAgent would manage the iterative process. The CriticAgent could be designed to return a "STOP" signal when the document reaches a satisfactory quality level, preventing further iterations. Alternatively, the max iterations parameter could be used to limit the process to a fixed number of cycles, or external logic could be implemented to make stop decisions. The loop would run at most five times, ensuring the iterative refinement doesn't continue indefinitely.

???+ "Full Code"

=== "Python"
    ```py
    --8<-- "examples/python/snippets/agents/workflow-agents/loop_agent_doc_improv_agent.py:init"
    ```

=== "TypeScript"
    ```typescript
    --8<-- "examples/typescript/snippets/agents/workflow-agents/loop_agent_doc_improv_agent.ts:init"
    ```

=== "Go"
    ```go
    --8<-- "examples/go/snippets/agents/workflow-agents/loop/main.go:init"
    ```

=== "Java"
    ```java
    --8<-- "examples/java/snippets/src/main/java/agents/workflow/LoopAgentExample.java:init"
    ```

!!! tip "Global instructions for all agents"

Apply consistent rules or identity across all agents in your workflow using  `GlobalInstructionPlugin` registered on your `App` or `Runner` object. Do not use the `global_instruction` parameter on `Agent` which is deprecated since ADK Python v1.16.0.