ContextQMD
Back to Adk Python

Task Mode: Structured Delegation

.agents/skills/adk-workflow/references/task-mode.md

2.0.0b18.2 KB
Original Source

Task Mode: Structured Delegation

Delegate structured tasks to sub-agents with typed input/output schemas.

Overview

ADK agents support three delegation modes via the mode parameter on Agent:

ModeTool GeneratedUser InteractionCompletion
chat (default)transfer_to_agentFull conversationalAgent transfers back
taskrequest_task_{name}Multi-turn (can chat with user)Calls finish_task
single_turnrequest_task_{name}None (autonomous)Calls finish_task

Imports

python
from google.adk import Agent
from pydantic import BaseModel

Note: Task mode uses Agent (aliased from LlmAgent) from google.adk. Both task sub-agents and coordinators use the same Agent class — set mode='task' or mode='single_turn' on sub-agents.

Task Mode (mode='task')

A task agent receives structured input via request_task_{name}, can interact with the user for clarification, and returns structured output via finish_task.

Delegation Lifecycle

  1. User asks the coordinator to do something
  2. Coordinator calls request_task_{agent_name}(...) with structured input
  3. Task agent receives the input, works on it (may use tools, may chat with user)
  4. Task agent calls finish_task(...) with structured output
  5. Coordinator receives the result and responds to the user

Example

python
from google.adk import Agent
from pydantic import BaseModel

class ResearchInput(BaseModel):
  topic: str
  depth: str = 'standard'

class ResearchOutput(BaseModel):
  summary: str
  key_findings: str
  confidence: str

def search_web(query: str) -> str:
  """Search the web for information."""
  return f'Results for "{query}": ...'

def analyze_sources(sources: str) -> str:
  """Analyze and synthesize source material."""
  return f'Analysis of {len(sources.split())} words complete.'

researcher = Agent(
    name='researcher',
    mode='task',
    input_schema=ResearchInput,
    output_schema=ResearchOutput,
    instruction=(
        'You are a research assistant. When given a topic:\n'
        '1. Use search_web to find information.\n'
        '2. Use analyze_sources to synthesize findings.\n'
        '3. If the user asks for changes, adjust your research.\n'
        '4. Call finish_task with summary, key_findings, and confidence.'
    ),
    description='Researches topics using web search and analysis.',
    tools=[search_web, analyze_sources],
)

root_agent = Agent(
    name='coordinator',
    model='gemini-2.5-flash',
    sub_agents=[researcher],
    instruction=(
        'When the user asks you to research something, delegate to'
        ' the researcher using request_task_researcher. After the'
        ' researcher completes, summarize the results for the user.'
    ),
)

Single-Turn Mode (mode='single_turn')

A single-turn agent completes autonomously with no user interaction. It receives input, does its work, and returns a result.

Example

python
class SummaryOutput(BaseModel):
  summary: str
  word_count: int
  key_points: str

def extract_text(url: str) -> str:
  """Extract text from a URL."""
  return f'Extracted content from {url}: ...'

summarizer = Agent(
    name='summarizer',
    mode='single_turn',
    output_schema=SummaryOutput,
    instruction=(
        'Summarize the document:\n'
        '1. Use extract_text to get content.\n'
        '2. Call finish_task with summary, word_count, key_points.\n'
        'Complete autonomously without user interaction.'
    ),
    description='Summarizes documents autonomously.',
    tools=[extract_text],
)

root_agent = Agent(
    name='coordinator',
    model='gemini-2.5-flash',
    sub_agents=[summarizer],
    instruction='Delegate summarization to summarizer via request_task_summarizer.',
)

Input and Output Schemas

Custom Schemas (Pydantic Models)

Define input_schema and/or output_schema with Pydantic BaseModel:

python
class TaskInput(BaseModel):
  query: str
  max_results: int = 10
  format: str = 'text'

class TaskOutput(BaseModel):
  results: str
  count: int
  status: str

agent = Agent(
    name='worker',
    mode='task',
    input_schema=TaskInput,    # Validates request_task_worker args
    output_schema=TaskOutput,  # Validates finish_task args
    ...
)

Default Schemas

When no custom schema is provided:

Default input (used by request_task_{name}):

python
class _DefaultTaskInput(BaseModel):
  goal: str | None = None
  background: str | None = None

Default output (used by finish_task):

python
class _DefaultTaskOutput(BaseModel):
  result: str

Auto-Generated Tools

request_task_{agent_name}

Auto-generated on the coordinator for each mode='task' or mode='single_turn' sub-agent. The tool name is request_task_{agent.name}.

  • Parameters come from input_schema (or default: goal, background)
  • Description includes the agent's description field
  • Validates input against the schema before delegating

finish_task

Auto-generated on the task agent itself. Called by the task agent when work is complete.

  • Parameters come from output_schema (or default: result)
  • Validates output against the schema before signaling completion
  • Sets tool_context.actions.finish_task with a TaskResult

Mixed-Mode Patterns

Combine task and single-turn agents under one coordinator:

python
# Interactive: user can discuss options
flight_searcher = Agent(
    name='flight_searcher',
    mode='task',
    input_schema=FlightSearchInput,
    output_schema=FlightSearchOutput,
    instruction='Search flights, discuss with user, then finish_task.',
    description='Searches and books flights interactively.',
    tools=[search_flights, book_flight],
)

# Autonomous: no user interaction
weather_checker = Agent(
    name='weather_checker',
    mode='single_turn',
    output_schema=WeatherOutput,
    instruction='Check weather and call finish_task. No user interaction.',
    description='Checks weather for a destination.',
    tools=[get_weather],
)

# Autonomous: no user interaction
hotel_finder = Agent(
    name='hotel_finder',
    mode='single_turn',
    output_schema=HotelOutput,
    instruction='Find hotels and call finish_task. No user interaction.',
    description='Finds hotels for a destination.',
    tools=[find_hotels],
)

root_agent = Agent(
    name='travel_planner',
    model='gemini-2.5-flash',
    sub_agents=[flight_searcher, weather_checker, hotel_finder],
    instruction=(
        'Help users plan trips:\n'
        '- request_task_weather_checker: autonomous weather check\n'
        '- request_task_hotel_finder: autonomous hotel search\n'
        '- request_task_flight_searcher: interactive flight booking'
    ),
)

Key Rules

  • Both task sub-agents and coordinators use Agent from google.adk
  • Each sub-agent needs a description (used in the auto-generated tool description)
  • input_schema and output_schema are optional; defaults are provided
  • Sub-agents inherit model from the coordinator if not set
  • finish_task instructions are auto-injected into the task agent's LLM context
  • Single-turn agents receive an extra instruction telling them no user replies will come

Task Mode vs Chat Mode

FeatureChat (transfer_to_agent)Task (request_task)
InputFree-form conversationStructured (schema-validated)
OutputFree-form conversationStructured (schema-validated)
Control flowAgent decides when to transfer backAgent calls finish_task
User interactionFull chattask: multi-turn; single_turn: none
Tool nametransfer_to_agentrequest_task_{name}
Parallel delegationNot supportedSupported (multiple request_task calls)

Source File Locations

ComponentFile
Agent/LlmAgent (mode, schemas)src/google/adk/agents/llm_agent.py
BaseLlmFlow (base flow class)src/google/adk/flows/llm_flows/base_llm_flow.py
RequestTaskToolsrc/google/adk/agents/llm/task/_request_task_tool.py
FinishTaskToolsrc/google/adk/agents/llm/task/_finish_task_tool.py
TaskRequest, TaskResultsrc/google/adk/agents/llm/task/_task_models.py
Task samplescontributing/task_samples/