Parallel Agent

Purpose

The Parallel Agent subtopic addresses the need to execute multiple sub-agents concurrently within the broader scope of Agent Workflow Management (80558). Unlike the Sequential Agent that runs sub-agents one after another, the Parallel Agent enables simultaneous execution of multiple sub-agents in isolated contexts. This concurrency allows for efficient handling of tasks that benefit from parallelism, such as:

• Running diverse algorithms or models simultaneously on the same input.

• Generating multiple independent responses or perspectives for evaluation.

• Improving throughput by leveraging concurrent processing capabilities.

This subtopic is crucial for orchestrating complex AI workflows where multiple parallel attempts or viewpoints enhance the overall system's effectiveness and speed.

Functionality

The core functionality of the Parallel Agent revolves around orchestrating the concurrent execution of its sub-agents while preserving isolated invocation contexts. Key features include:

• Isolated Contexts: Each sub-agent runs with its own invocation context that inherits shared session, memory, and artifact references but maintains separate branches to avoid state conflicts.

• Concurrent Execution: Utilizes Go's errgroup package to manage goroutines running sub-agents concurrently, capturing errors and ensuring coordinated cancellation.

• Event Streaming: Collects events produced by all sub-agents through a shared channel and yields them asynchronously to the caller, preserving a unified event stream despite parallelism.

• Graceful Cancellation: Listens for context cancellation and terminates sub-agent executions promptly, ensuring efficient resource usage.

• Error Propagation: If any sub-agent returns an error, the Parallel Agent propagates it, allowing upstream handlers to respond accordingly.

This approach enhances the parent topic’s orchestration capabilities by enabling parallelism as an alternative execution pattern alongside sequential and loop workflows (Sequential Agent, Loop Agent).

Core Workflow Outline

1. Setup: For each sub-agent, create a new invocation context with a unique branch name to isolate execution paths.

2. Concurrent Run: Launch a goroutine for each sub-agent using an error group to coordinate lifecycle and error handling.

3. Event Collection: Sub-agents emit events via their own Run method; these are funneled into a shared resultsChan.

4. Yielding Events: The Parallel Agent returns a unified iterator that yields events from all sub-agents as they become available.

5. Cancellation and Cleanup: Upon cancellation or completion, channels are closed, and goroutines exit cleanly.

Selected Code Snippet

func run(ctx agent.InvocationContext) iter.Seq2[*session.Event, error] {
    var (
        errGroup, errGroupCtx = errgroup.WithContext(ctx)
        doneChan              = make(chan bool)
        resultsChan           = make(chan result)
    )

    for _, sa := range ctx.Agent().SubAgents() {
        branch := fmt.Sprintf("%s.%s", ctx.Agent().Name(), sa.Name())
        subAgent := sa
        errGroup.Go(func() error {
            subCtx := icontext.NewInvocationContext(errGroupCtx, icontext.InvocationContextParams{
                Artifacts:   ctx.Artifacts(),
                Memory:      ctx.Memory(),
                Session:     ctx.Session(),
                Branch:      branch,
                Agent:       subAgent,
                UserContent: ctx.UserContent(),
                RunConfig:   ctx.RunConfig(),
            })
            return runSubAgent(subCtx, subAgent, resultsChan, doneChan)
        })
    }

    go func() {
        _ = errGroup.Wait()
        close(resultsChan)
    }()

    return func(yield func(*session.Event, error) bool) {
        defer close(doneChan)
        for res := range resultsChan {
            if !yield(res.event, res.err) {
                break
            }
        }
    }
}

This snippet demonstrates the creation of isolated contexts per sub-agent, concurrent execution with error grouping, and yielding of aggregated results.

Integration

The Parallel Agent integrates tightly with the parent topic Agent Workflow Management (80558) by implementing one of the core workflow agents alongside Sequential and Loop Agents. It complements these subtopics by providing a parallel execution strategy, thus broadening the orchestration patterns available for complex AI workflows.

• Sub-Agent Composition: The Parallel Agent manages and invokes sub-agents, which themselves may be LLM agents, other workflow agents, or custom agents from AI Agent Framework.

• Session and State Sharing: Despite isolated invocation branches, the Parallel Agent shares session, memory, and artifact services among sub-agents, facilitating coordinated interaction with persistent state (Session Management, Artifact Management).

• Invocation Context Isolation: Uses the internal invocation context utilities to create separate branches for each sub-agent, ensuring clean state separation and traceability.

• Error and Cancellation Propagation: Works seamlessly with the Agent Execution Runner ([80560]) which handles execution lifecycle and cancellation signals.

• Composable with Other Workflow Agents: Enables hybrid workflows by nesting Parallel Agents within Sequential or Loop Agents, or vice versa, allowing complex execution graphs.

Diagram

flowchart TD
Start[Start ParallelAgent Run]
SubAgent1[Sub-Agent 1 Run]
SubAgent2[Sub-Agent 2 Run]
SubAgentN[Sub-Agent N Run]
ErrGroup[Error Group Wait]
ResultsChan[Collect Events]
YieldEvents[Yield Events to Caller]
DoneChan[Done / Cancel Signal]
Start -->|Create isolated contexts| SubAgent1
Start --> SubAgent2
Start --> SubAgentN
SubAgent1 --> ResultsChan
SubAgent2 --> ResultsChan
SubAgentN --> ResultsChan
ErrGroup -->|Wait for all sub-agents| ResultsChan
ResultsChan --> YieldEvents
YieldEvents --> DoneChan

This flowchart visualizes the Parallel Agent’s core process: spawning sub-agents with isolated contexts, collecting their events concurrently, and yielding a merged stream of events to the caller, with error group coordination and graceful cancellation.