Added iterator agent for ADK pipeline #1611

[vivek100]

Add ArrayIteratorAgent for Array Iteration Functionality

Summary
Implements ArrayIteratorAgent to provide built-in array iteration functionality for the ADK. This agent allows developers to iterate over arrays in session state and pass each element to a sub-agent for processing, addressing a common workflow pattern that was previously missing from the ADK.

Changes Made

✅ Added ArrayIteratorAgent class in src/google/adk/agents/array_iterator_agent.py
✅ Implemented single sub-agent constraint with validation
✅ Added support for nested array key access using dot notation (e.g., user_data.customers)
✅ Implemented automatic result collection from sub-agent's output_key
✅ Added comprehensive unit tests in tests/unittests/agents/test_array_iterator_agent.py
✅ Updated agent exports and imports for proper integration
✅ Added documentation and examples
Key Features

Single Sub-Agent Pattern: Enforces exactly one sub-agent to keep iteration focused and simple
Nested State Access: Supports dot notation for accessing nested arrays (app:config.items, user.data.list)
Automatic Collection: Collects results from sub-agent's output_key into an array
Configurable Context: Passes each array element via configurable item_key (default: current_item)
Optional Limits: Supports max_items parameter for processing subsets
Robust Error Handling: Validates array existence, sub-agent count, and handles edge cases
Usage Example

Sub-agent processes individual items

processor = LlmAgent(
name="item_processor",
instruction="Process: {current_item}",
output_key="result"
)

Array iterator

iterator = ArrayIteratorAgent(
name="batch_processor",
array_key="items",
output_key="all_results",
sub_agents=[processor]
)
Testing

✅ Unit tests cover all core functionality
✅ Edge cases tested (empty arrays, missing keys, validation errors)
✅ Integration with existing ADK patterns verified
✅ Nested state access thoroughly tested
✅ Error handling and validation confirmed
Breaking Changes
None - this is a new feature addition that doesn't modify existing functionality.

Documentation

Added comprehensive docstrings following Google style
Included usage examples in class documentation
Added type hints for all parameters and methods
Fixes #1610

[gemini-code-assist]

Summary of Changes

Hello @vivek100, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the ADK's capabilities by introducing the ArrayIteratorAgent. This new agent provides a structured and efficient way to process collections of data within agent workflows. It allows for iterating over arrays in the session state, applying a single, focused sub-agent to each item, and then optionally collecting the results. This feature is crucial for handling common patterns like batch processing, document analysis, or data transformation, where a series of operations needs to be performed on multiple similar data points. The agent supports nested key access for flexible data handling and includes built-in validation and error handling to ensure robust operation.

Highlights

• New ArrayIteratorAgent: Introduces a dedicated agent for iterating over arrays in the session state, applying a sub-agent to each element.
• Single Sub-Agent Constraint: Enforces that the ArrayIteratorAgent operates with exactly one sub-agent, promoting focused iteration.
• Nested Key Support: Allows accessing array data and storing results using dot notation for complex, nested session state structures.
• Automatic Result Collection: Automatically gathers outputs from the sub-agent into a new array in the session state if an output_key is specified.
• Robust Error Handling & Validation: Includes validation for sub-agent count, array existence, and type, along with handling for escalation during iteration.
• Comprehensive Samples & Tests: Provides detailed usage examples in agent.py and README.md, alongside thorough unit tests.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new ArrayIteratorAgent for processing arrays in session state, a valuable addition for common workflow patterns. The implementation is well-structured with good error handling and comprehensive unit tests. My review focuses on a critical issue in the result collection logic that fails to handle structured output from sub-agents correctly. I've also included suggestions to simplify the code and enhance test coverage to prevent similar issues in the future. Overall, this is a great feature, and with these fixes, it will be even more robust.

[vivek100]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the ArrayIteratorAgent, a useful addition for processing array data within the ADK pipeline. The implementation is solid, with good handling of nested keys and state management. The accompanying unit tests are comprehensive and cover a wide range of scenarios, ensuring the agent's reliability. The documentation and sample code are also well-written and provide clear guidance on usage. I've included a couple of suggestions to improve code clarity and documentation consistency.

[vivek100]

@gemini-code-assist can you look at the current implementation of agents in the main branch and create a pros and cons list of whether the itterator agent i created is helpful or not or there are other features already in the agent which we can use to achieve this. The idea is to give this option out of the box and option to connect this iterator agent with any of the available agents.

[gemini-code-assist]

Hi @vivek100,

That's an excellent question! I've reviewed the ArrayIteratorAgent and compared its functionality with existing agent types in the ADK. Here's a breakdown of its helpfulness and how it fits into the current agent ecosystem:

ArrayIteratorAgent: Pros and Cons

Pros:

• Dedicated Array Processing: The ArrayIteratorAgent directly addresses a very common and crucial pattern in agent workflows: iterating over collections of data. This was previously a gap that would require more complex, manual orchestration.
• Simplified Workflow: It significantly simplifies the implementation of batch processing, document analysis, or any task where a sub-agent needs to operate on individual items from a list. It abstracts away the boilerplate logic for managing iteration, passing context, and collecting results.
• Structured Data Flow: By explicitly defining array_key, item_key, and output_key, it enforces a clear and predictable data flow for array-based operations within the session state, including support for nested keys.
• Automatic Result Collection: The optional output_key feature automates the aggregation of results from each sub-agent execution into a new array, which is highly convenient.
• Robust Error Handling: Includes built-in validation for the array's existence and type, and gracefully handles escalation from sub-agents by stopping further iteration.
• Complements Existing Agents: It doesn't replace SequentialAgent, ParallelAgent, or LoopAgent but rather enhances them. It acts as an orchestrator for data-driven iteration, allowing any of these other agents (or custom ones) to be the single sub-agent that processes each item.

Cons (or Design Considerations):

• Single Sub-Agent Constraint: While a design choice to keep the iteration logic focused, it means that if complex multi-step processing is needed for each item, that logic must be encapsulated within a SequentialAgent or ParallelAgent that then becomes the single sub-agent of the ArrayIteratorAgent. This is well-documented and demonstrated in the samples, but it's a pattern users need to be aware of.
• Live Mode Not Yet Supported: As noted in the code, the _run_live_impl is not yet implemented, which might be a limitation for real-time streaming scenarios involving array iteration.

Comparison with Existing Features

• SequentialAgent / ParallelAgent: These agents are designed to execute a sequence or parallel set of sub-agents for a single overall task or input. They do not inherently provide mechanisms for iterating over a collection of items and applying a sub-agent to each one. The ArrayIteratorAgent fills this specific need.
• LoopAgent: The LoopAgent is primarily for repeating a set of actions a fixed number of times or until a general condition is met. It doesn't automatically manage iterating over elements of an array from session state and injecting each element as context for a sub-agent. While one could manually implement array iteration logic within a LoopAgent (e.g., by popping items from an array in session state), the ArrayIteratorAgent provides a much cleaner, more explicit, and less error-prone abstraction for this specific use case.

Conclusion on Helpfulness

The ArrayIteratorAgent is definitely helpful and a valuable addition to the ADK. It addresses a fundamental pattern for processing data collections that was not natively and elegantly supported by existing agents. It provides a clear, robust, and efficient way to build workflows that involve iterating over arrays, making complex data processing pipelines much easier to construct and understand.

Connecting with Any Available Agents

Yes, the design allows for the ArrayIteratorAgent to connect with any available agent as its single sub-agent. Since LlmAgent, SequentialAgent, ParallelAgent, and any custom agents you define all inherit from BaseAgent, they can all be passed as the sub_agents list (containing a single element) to the ArrayIteratorAgent. This flexibility is a major strength, enabling highly modular and powerful workflows where the iteration logic is cleanly separated from the item-processing logic.

Your implementation provides a much-needed abstraction that will make many common agent development patterns significantly simpler and more robust. Great work!