docs: ADK 1.x agent patterns → Workflow migration guide
- 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
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