google / google/adk-docs

docs: ADK 1.x agent patterns → Workflow migration guide

Open
#2,185 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
1.5k
Forks
1.3k
Avg merge
7d 1h
Merged PRs (30d)
34

Description

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

ADK 1.x codebases commonly used `SequentialAgent`, `ParallelAgent`, and `LoopAgent`. On adk-python `main`, these classes are `@deprecated` in favor of `Workflow`, with the note that Workflow cannot yet be used as an `LlmAgent` sub-agent.

The [ADK 2.0 overview](https://adk.dev/2.0/) documents Workflow **runtime** breaking changes (events, session schema) but not a **pattern migration** table:

| Old pattern | ADK 2 direction |
|---|---|
| `ParallelAgent` fan-out | `Workflow` + `JoinNode` |
| `LoopAgent` critique | `Workflow` + loop / `RequestInput` |
| `SequentialAgent` as `sub_agent` | **Workflow-as-Tool** on `Agent(tools=[...])` (ADK 2.4+; see closed [google/adk-python#5872](https://github.com/google/adk-python/issues/5872)) |

Samples exist ([`legacy_workflows/`](https://github.com/google/adk-python/tree/main/contributing/samples/legacy_workflows), [`workflows/`](https://github.com/google/adk-python/tree/main/contributing/samples/workflows)) but there is no single narrative doc on adk.dev tying them together.

**Describe the solution you'd like**

A migration guide page on adk-docs mapping deprecated agents to Workflow patterns, linking to official samples (including `node_as_tool` for Workflow-as-Tool), and explicitly referencing #5872 resolution (Workflow-as-Tool, not Workflow-as-sub-agent).

**Describe alternatives you've considered**

- More samples only: already present; need narrative.
- Re-opening Workflow-as-sub-agent: rejected per maintainer direction in #5872.

**Additional context**

Willing to open a PR with the guide page after this issue. Optional short cross-link in adk-python workflow docs can follow separately.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing ADK 2.0 overview and the contributing/samples/legacy_workflows/ and contributing/samples/workflows/ directories. Use the closed google/adk-python#5872 discussion and its node_as_tool sample to verify the Workflow-as-Tool direction. Done means a single migration guide maps SequentialAgent, ParallelAgent, and LoopAgent patterns to Workflow alternatives, links official samples, and clearly distinguishes Workflow-as-Tool from Workflow-as-sub-agent.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.