Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions contributing/samples/workflows/adaptive_team/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# ADK Adaptive Team Sample

## Overview

This sample coordinates two specialists from a shared plan. A coordinator
writes the plan, picks who should work next, and replaces the plan when two
rounds in a row do not move the task forward. The workflow stops with one
answer.

The helper is `adaptive_team` in `google.adk.labs.adaptive_team`. It is
experimental.

## Sample Inputs

- `Compare the energy use of electric and gas heating for a small apartment, and name the bigger uncertainty.`

The researcher gathers facts. The analyst compares them. The coordinator
answers after the progress check says the task is covered, or after the
round and replan limits.

- `What would change that comparison if the apartment were heated only on weekends?`

A follow-up in the same session starts a new plan. The previous ledger is
left behind with the previous invocation.

## Graph

```mermaid
graph TD
START --> driver[driver <br/>PYTHON FUNCTION]
driver -.->|ctx.run_node| coordinator
driver -.->|ctx.run_node| researcher
driver -.->|ctx.run_node| analyst
```

## How To

Build the workflow from a coordinator and the specialists. The coordinator's
instruction is extra guidance. The helper writes the planning, progress, and
final-answer instructions, and it does not call the coordinator's tools.

```python
root_agent = adaptive_team(
name="energy_brief",
manager=coordinator,
participants=[researcher, analyst],
max_rounds=6,
stall_limit=2,
replan_limit=1,
)
```

Set `review_plan=True` to pause for a yes or no on each plan. The reply is a
`PlanDecision`. Pass `approved` and, when rejecting, `notes` describing the
change. A rejection spends one entry from `replan_limit`.

Read the ledger from session state with `team_state_key("energy_brief")`.
Coordinator events set `custom_metadata["adaptive_team"]["kind"]` to `plan`,
`replan`, `progress`, or `answer`. Specialist events keep the specialist as
the author.

## Related Guides

- [adaptive_team](../../../../docs/guides/labs/adaptive_team/team/index.md) - Building a workflow that plans, selects specialists, and replans when work stalls.
- [Dynamic nodes](../../../../docs/guides/workflow/dynamic_nodes/index.md) - Running a node from inside another node with `ctx.run_node`.
- [Workflow](../../../../docs/guides/workflow/workflow/index.md) - The graph the helper returns.
15 changes: 15 additions & 0 deletions contributing/samples/workflows/adaptive_team/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

from . import agent
53 changes: 53 additions & 0 deletions contributing/samples/workflows/adaptive_team/agent.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""A coordinator that plans, picks a specialist, and replans if work stalls."""

from google.adk import Agent
from google.adk.labs.adaptive_team import adaptive_team

researcher = Agent(
name='researcher',
description='Collects qualitative facts and cites where they come from.',
instruction=(
'Gather the facts the assignment asks for. Do not compute totals'
' or give the final recommendation.'
),
)

analyst = Agent(
name='analyst',
description='Compares figures and states the main uncertainty.',
instruction=(
'Use the facts you are given. Show the comparison in words and'
' name the largest uncertainty.'
),
)

coordinator = Agent(
name='coordinator',
description='Turns an open question into a plan and a final answer.',
instruction=(
'Prefer sources a reader can check. Say when a number is an estimate.'
),
)

root_agent = adaptive_team(
name='energy_brief',
manager=coordinator,
participants=[researcher, analyst],
max_rounds=6,
stall_limit=2,
replan_limit=1,
)
1 change: 1 addition & 0 deletions docs/guides/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ This directory contains specific developer guides for the ADK Python implementat
* [TypesafeClassifier](integrations/typesafe/typesafe_classifier/index.md) - Answering `Choice`, `Binary`, and `Score` questions with TypeSafe's Jev decision models instead of a model turn.

### Labs
* [adaptive_team](labs/adaptive_team/team/index.md) - Coordinating specialists from a shared plan, with stall detection, replanning, and an optional pause to accept the plan.
* [AntigravityAgent](labs/antigravity/index.md) - Runs a Google Antigravity SDK agent as an ADK agent node.
* [ClassifierNode](labs/classifiers/classifier_node/index.md) - Routing a workflow on a classifier's answer to one `Choice` or `Binary` question.
* [LlmClassifier](labs/classifiers/llm_classifier/index.md) - Answering `Choice`, `Binary`, and `Score` questions with any model, in one structured-output call.
Expand Down
194 changes: 194 additions & 0 deletions docs/guides/labs/adaptive_team/team/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
# adaptive_team

`adaptive_team` builds a workflow that answers an open task by planning it,
choosing one specialist at a time, and replacing the plan when the work
stalls.

## Introduction

Some tasks do not have a fixed path. A research brief, a comparison, or a
draft that needs both reading and calculation can start with a plan and then
change that plan when a step repeats itself. `Workflow` can already run a
Python function that calls `ctx.run_node`. What each application would
otherwise rebuild is the plan, the record of each turn, the stall limit, the
optional pause for a person to accept the plan, and the final answer.

`adaptive_team` returns that workflow. The caller supplies a coordinator
`LlmAgent` and the specialist agents. The helper supplies the instructions
for the plan, the progress check, and the final answer. The coordinator's
own instruction is appended as extra guidance. Specialist tools stay on the
specialists. The coordinator's tools are not called during those three
phases, because each phase has to return one structured object or one final
reply.

The package is experimental. `ADAPTIVE_TEAM` is enabled by default and logs a
warning the first time the helper is used. Set `ADK_DISABLE_ADAPTIVE_TEAM=1`
to turn it off.

## Get started

The workflow below compares two heating fuels. The researcher collects facts.
The analyst compares them. The coordinator's instruction only adds guidance
about sources and estimates.

```python
from google.adk import Agent
from google.adk.labs.adaptive_team import adaptive_team

researcher = Agent(
name="researcher",
description="Collects qualitative facts and cites where they come from.",
instruction="Gather the facts the assignment asks for.",
)
analyst = Agent(
name="analyst",
description="Compares figures and states the main uncertainty.",
instruction="Compare the facts you are given.",
)
coordinator = Agent(
name="coordinator",
description="Turns an open question into a plan and a final answer.",
instruction="Prefer sources a reader can check.",
)

root_agent = adaptive_team(
name="energy_brief",
manager=coordinator,
participants=[researcher, analyst],
max_rounds=6,
stall_limit=2,
replan_limit=1,
)
```

Run it the same way as any other workflow. The workflow's output is the final
answer text.

## How it works

One driver node inside the workflow owns the loop.

1. The coordinator writes a `TaskPlan`: a goal, facts already known, open
questions, and ordered steps. Each step is supposed to name a specialist
from the roster.
1. When `review_plan` is true, the workflow pauses with `RequestInput` and a
`PlanDecision` schema. Approving the plan continues it. Rejecting it, and
sending notes, spends one replacement and asks for a new plan. With no
replacements left, the current plan continues.
1. Each round, the coordinator returns a `RoundAssessment`. `satisfied` ends
the loop. Otherwise `participant` must be a roster name and `assignment`
is the user message for that specialist.
1. The specialist runs through `ctx.run_node` and the turn is appended to the
ledger. A turn is stalled when the assessment says so, when that
specialist was just given the same assignment, or when the name is not on
the roster or the assignment is empty.
1. `stall_limit` stalled turns in a row replace the plan, up to
`replan_limit` replacements. The new plan is shown the previous plan and
the reason the team stalled. After the last allowed stall, the coordinator
writes a best-effort answer instead.
1. `max_rounds` counts specialist turns across every attempt. Reaching it
also writes the answer.

The ledger is a `TeamSnapshot` in session state, under
`team_state_key(name)`. It stores the task, the plan, every round, the stall
window, and the final answer. The snapshot is tied to the current invocation.
A pause for review stays in that invocation, so the run continues from the
saved ledger and does not repeat model calls that already finished. A new
user message is a new invocation and starts a new ledger.

Coordinator events set `custom_metadata["adaptive_team"]` to a dict whose
`kind` is a `TeamNotice`: `plan`, `replan`, `progress`, or `answer`. The
`answer` event's output is the final text. Specialist events keep the
specialist's author, so a caller can show those turns without treating them
as the answer.

`stop_reason` on the snapshot is one of `satisfied`, `round_limit`,
`replan_limit`, or `empty_task`.

## Configuration options

| Option | Type | Default | Description |
| :------------- | :---------------------- | :--------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `str` | | Workflow name. Also the suffix of the session-state key. |
| `manager` | `LlmAgent` | | Coordinator. Its instruction is extra guidance. Its tools are not used for the plan, the progress check, or the answer. |
| `participants` | sequence of `BaseAgent` | | Specialists the coordinator may call. Names must be unique Python identifiers and must not match the coordinator or its phase names. |
| `max_rounds` | `int` | `8` | Maximum specialist turns across all attempts. |
| `stall_limit` | `int` | `2` | Consecutive stalled turns before the plan is replaced. |
| `replan_limit` | `int` | `1` | How many replacement plans are allowed. Zero keeps the first plan only. |
| `review_plan` | `bool` | `False` | Pause for a `PlanDecision` before each plan is executed. |
| `description` | `str` | a short sentence | Description stored on the workflow. |

Give every specialist a `description`. The roster the coordinator sees is the
name plus that description. The specialist's own `instruction` still applies
when that agent runs.

`stall_limit` counts consecutive stalled turns, not every turn. A turn that
the coordinator marks as progress resets the streak. Replacing the plan also
resets the streak. Earlier turns stay in the transcript so the new plan and
the final answer can use them.

A rejection during review spends the same budget as a stall replacement. The
notes on the rejection are the reason the next plan has to address.

## Advanced applications

Pause for a person to edit the plan before any specialist runs:

```python
root_agent = adaptive_team(
name="energy_brief",
manager=coordinator,
participants=[researcher, analyst],
review_plan=True,
replan_limit=2,
)
```

The pause is a normal `adk_request_input` function call. Resume it with a
`PlanDecision`, for example `{"approved": false, "notes": "focus on cost"}`.
The interrupt id is `review-v` plus the plan version, starting at
`review-v0`.

Read the ledger after the run:

```python
from google.adk.labs.adaptive_team import TeamSnapshot
from google.adk.labs.adaptive_team import team_state_key

snapshot = TeamSnapshot.model_validate(
session.state[team_state_key("energy_brief")]
)
```

Filter the event stream by kind when the caller wants the plan and the answer
without assembling them from specialist text:

```python
from google.adk.labs.adaptive_team import TEAM_EVENT_METADATA_KEY
from google.adk.labs.adaptive_team import TeamNotice

kind = (event.custom_metadata or {}).get(TEAM_EVENT_METADATA_KEY, {})
if kind.get("kind") == TeamNotice.ANSWER:
final_answer = event.output
```

## Limitations

The coordinator phases do not see session history and do not call the
manager's tools. Everything they should know has to fit in the task, the
plan, and the transcript. A specialist keeps the tools and the mode
configured on that agent.

Participant names are matched exactly, after stripping surrounding space.
Descriptions are the only roster text the coordinator is given, so a missing
description makes the roster less useful.

The ledger lives in session state for the invocation. It is not a memory
service, and a new user message does not continue the previous plan.

The feature is experimental. Field names on `TaskPlan`, `RoundAssessment`,
`PlanDecision`, and `TeamSnapshot` can still change.

## Related samples

- [Adaptive team](../../../../../contributing/samples/workflows/adaptive_team/agent.py) - Two specialists and a coordinator with a stall limit of two rounds.
4 changes: 4 additions & 0 deletions src/google/adk/features/_feature_registry.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
class FeatureName(str, Enum):
"""Feature names."""

ADAPTIVE_TEAM = "ADAPTIVE_TEAM"
AGENT_CONFIG = "AGENT_CONFIG"
AGENT_ENGINE_SANDBOX_ENVIRONMENT = "AGENT_ENGINE_SANDBOX_ENVIRONMENT"
AGENT_STATE = "AGENT_STATE"
Expand Down Expand Up @@ -121,6 +122,9 @@ class FeatureConfig:

# Central registry: FeatureName -> FeatureConfig
_FEATURE_REGISTRY: dict[FeatureName, FeatureConfig] = {
FeatureName.ADAPTIVE_TEAM: FeatureConfig(
FeatureStage.EXPERIMENTAL, default_on=True
),
FeatureName.AGENT_CONFIG: FeatureConfig(
FeatureStage.STABLE, default_on=True
),
Expand Down
41 changes: 41 additions & 0 deletions src/google/adk/labs/adaptive_team/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Coordinate specialists with a shared plan and a stall limit.

Experimental. The helper returns an ordinary workflow, and the shape of
the ledger may change.
"""

from ._constants import TEAM_EVENT_METADATA_KEY
from ._constants import team_state_key
from ._team import adaptive_team
from ._types import PlanDecision
from ._types import RoundAssessment
from ._types import RoundNote
from ._types import TaskPlan
from ._types import TeamNotice
from ._types import TeamSnapshot

__all__ = [
'PlanDecision',
'RoundAssessment',
'RoundNote',
'TEAM_EVENT_METADATA_KEY',
'TaskPlan',
'TeamNotice',
'TeamSnapshot',
'adaptive_team',
'team_state_key',
]
Loading
Loading