Atefeh Rajabi
7.4 KiB
Build collaborative agent teams
Some complex tasks may require multiple agents with specific responsibilities and benefit from less structured procedures, particularly for iterative processes with several, substantial sub-tasks. In a collaborative agent team in ADK, a coordinator agent handles delegation of tasks to one or more subagents. This approach makes it easier to build complex, self-managing agent systems, with subagents defined to handle specific tasks, and automatic return to the parent after completing a task.
When using this self-managed agent team approach, the subagents are assigned an operating mode to manage their behavior and limit their scope of work. These modes set general behavior guidelines for subagents and create more predictable and reliable mulit-agent workflows. The following settings are available for collaboration modes:
- Chat: Full user interaction, manual return to parent agent (default, current behavior)
- Task: User interaction for clarifications with automatic return to parent agent
- Single-turn: No user interaction with automatic return and can be run in parallel
This guide covers how to use modes for your subagents and how these modes impact agent behavior.
!!! warning "Disabled: Task mode in graph-based workflows"
The collaborative mode `task` behavior is disabled for use in
graph-based workflows in ADK Python v2.0.0. This feature
is expected to be re-enabled in a future release.
Get started
The following code example shows how to set operating modes for a small team of subagents and assign them to a coordinator agent:
=== "Python"
```python
from google.adk import Agent
weather_agent = Agent(
name="weather_checker",
mode="single_turn", # no user interaction
tools=[get_weather, user_info, geocode_address],
)
flight_agent = Agent(
name="flight_booker",
mode="task", # can ask user questions
input_schema=FlightInput,
output_schema=FlightResult,
tools=[search_flights, book_flight],
)
root = Agent(
name="travel_planner", # coordinator agent
sub_agents=[weather_agent, flight_agent],
# Auto-injects delegation tools named after each subagent:
# weather_checker, flight_booker
)
```
=== "Go"
In ADK Go v2.0.0, the `Mode` field on `llmagent.Config` accepts the same
mode strings as Python: `"chat"`, `"task"`, and `"single_turn"`. Declaring
`SubAgents` on the coordinator agent causes ADK to automatically generate
a delegation tool for each subagent, named after the subagent itself,
exactly as in Python.
```go
--8<-- "examples/go/snippets/workflows/collaboration/main.go:get-started"
```
When you run this workflow, the travel_planner coordinator agent automatically
identifies and assigns tasks to the subagents. When a subagent completes
a task, it automatically returns to the coordinator agent.
For more information about structuring data using input_schema and
output_schema with agents, subagents, and workflow nodes, see
Data handling for agent workflows.
Mode configuration and behaviors
Each collaboration mode has specific behaviors and limitations associated with it. The following table compares the attributes of a subagent configured with each mode:
!!! warning "Caution: Mode only for subagents"
The ***mode*** setting is intended specifically for use with subagents invoked
by a coordinator parent agent. Do not configure a root agent with the mode
setting.
| Topic \ Mode | chat (default) |
task |
single_turn |
|---|---|---|---|
| Human in the Loop | Full interaction | For clarification only | Disallowed |
| User interaction | User chats freely with agent | Agent asks questions as needed | No user interaction |
| Control flow | Agent controls until manual handoff | Agent controls until task complete | Returns immediately after task |
| Parallel execution | Not supported | Not supported | Multiple tasks can run in parallel |
| Return to parent | Manual (via transfer) | Automatic (via finish_task) |
Automatic (with result) |
Table 1. Comparison of ADK Collaboration agent mode behavior and limitations.
Operating considerations
When using collaboration agent modes, there are a few control transfer and context management considerations to consider, as described in the following sections.
Workflow Node and Agent transfers
Agents configured with task or single-turn modes can be used as Workflow Agent graph nodes, and with LlmAgent instances. However the execution transfer behavior is different depending on the calling, or parent, agent:
As a workflow graph node: When a task or single-turn agent is placed within
a workflow graph — such as a SequentialAgent or ParallelAgent (Python
and Go prebuilt agents), or wrapped with workflow.NewAgentNode in the ADK Go
v2.0.0 graph engine — the agent executes its task. Upon completion, control
automatically advances to the next node based on the logic of the workflow
agent's graph.
As a transferee from an LlmAgent: When a parent LlmAgent transfers
control to a task agent via the delegation tool named after that subagent, the
task agent executes until it calls finish_task. At that point, control
automatically returns to the originating agent that initiated the transfer.
This behavior differs from default, chat mode agents, which require
explicit transfer_to_agent calls to hand back control.
| Invocation Context | After Task Completion |
|---|---|
| Workflow node | Advances to next node in the graph |
| Transfer from LlmAgent | Returns control to the originating agent |
This distinction allows the same task agent to be reused in both contexts without modification. The runtime determines the appropriate control flow based on how the agent was invoked.
Agent context isolation
Each task or single-turn mode agent operates in its own isolated session branch. When these agents operate in parallel, each agent only sees events from its own branch when building context for AI model calls, and cannot see what its peer agents are doing. Once all parallel branches complete, the parent agent receives the collected results and can proceed.
Known limitations
There are some known limitations with agent collaboration modes:
- Task mode agents must be leaf agents and cannot have subagents.