Based on our conversation about implementing the ArrayIteratorAgent for the ADK, I'll help you fill out the GitHub issue request with the relevant details:

GitHub Issue: Add ArrayIteratorAgent for Array Iteration Functionality

Is your feature request related to a problem? Please describe.

Currently, the ADK lacks built-in functionality to iterate over arrays and pass each element to sub-agents. While we have LoopAgent (runs with max_iterations), SequentialAgent, and ParallelAgent, there's no direct way to:

• Take an array from session state (e.g., a list of customers, items, or data points)
• Iterate through each element
• Pass each element to a sub-agent for processing
• Collect results back into an array

This forces developers to implement custom iteration logic or use workarounds, making array processing patterns unnecessarily complex in agent workflows.

Describe the solution you'd like

Add a new ArrayIteratorAgent that provides clean array iteration functionality with the following features:

1. Single Sub-Agent Pattern: Exactly one sub-agent (enforced with validation) to keep the iterator focused on iteration, not complex orchestration
2. Nested Array Key Support: Support dot notation for nested state access (e.g., user_data.customers, app:config.items)
3. Simple Output Collection: Collect results from sub-agent's output_key into an array automatically
4. Configurable Item Context: Pass each array element to sub-agent via configurable context key (default: current_item)
5. Optional Limits: Support max_items parameter for processing subsets

Example Usage:

# Sub-agent processes individual items
processor = LlmAgent(
    name="item_processor",
    instruction="Process this item: {current_item}",
    output_key="processed_result"
)

# Array iterator
array_agent = ArrayIteratorAgent(
    name="batch_processor",
    array_key="items",  # Path to array in state
    item_key="current_item",  # Context key for each item
    output_key="all_results",  # Collects sub-agent results
    sub_agents=[processor]  # Exactly one sub-agent
)

Describe alternatives you've considered

1. Complex Multi-Sub-Agent ArrayIteratorAgent: Initially considered supporting multiple sub-agents with various processing patterns (sequential, parallel, conditional), but this adds unnecessary complexity
2. Using Existing LoopAgent: Could use LoopAgent with custom logic, but requires manual array indexing and state management
3. Custom Agent Implementation: Developers can build their own, but this should be core functionality given its common use case
4. Extending SequentialAgent: Could extend existing agents, but array iteration is a distinct enough pattern to warrant its own agent type

Additional context

• This addresses a common pattern in data processing workflows where agents need to process lists of items
• The design follows the principle of "do one thing well" - focused solely on iteration
• Implementation should follow Google repository standards with proper error handling and validation
• Should integrate seamlessly with existing ADK patterns (output_key, state management, nested state access)
• Target use cases include: processing customer lists, batch data transformation, iterating through API responses, handling dynamic workflow items

This feature would significantly improve developer experience for array-based workflows while maintaining the ADK's clean, modular architecture.``