Assemble an ADK agent

Learning objective

Assemble an Agent Development Kit (ADK) agent whose model, instructions, tools, and subagents form one coherent capability. This lesson focuses on the agent definition, not on runners, events, sessions, or deployment.

Core idea

Treat an ADK agent definition as a reasoning boundary with attached capabilities:

• The model supplies language understanding and reasoning.
• The instruction defines the agent’s job, constraints, tool-use guidance, and response contract.
• The tools list exposes operations that the model can request.
• The sub_agents list exposes other reasoning boundaries to which the agent can delegate.

These parts must agree. Adding a tool does not guarantee that the model uses it, and mentioning a capability in an instruction does not make that capability exist. ADK’s LlmAgent, commonly imported as Agent, uses the model to decide what to do, including whether to call a tool. Its behavior is therefore nondeterministic and must be evaluated. See Simple agents with LlmAgent.

How it works

The following Python example uses ADK 2.0 collaborative-agent syntax. It gives the coordinator an order lookup tool and a focused policy subagent:

from google.adk import Agent


def lookup_order(order_id: str) -> dict:
    """Returns the recorded status and delivery age for an order."""
    # Replace this example result with a call to the order service.
    return {
        "order_id": order_id,
        "status": "delivered",
        "delivered_days_ago": 3,
    }


def lookup_refund_policy(country: str) -> dict:
    """Returns the approved refund window for a country."""
    # Replace this example result with a call to the policy service.
    return {"country": country, "refund_window_days": 14}


policy_agent = Agent(
    name="refund_policy_specialist",
    model="gemini-flash-latest",
    mode="single_turn",
    description="Checks refund eligibility from order facts and country policy.",
    instruction=(
        "Check eligibility only. Use lookup_refund_policy for the policy. "
        "Return the decision and the facts that support it. Never issue a refund."
    ),
    tools=[lookup_refund_policy],
)

root_agent = Agent(
    name="refund_support_coordinator",
    model="gemini-flash-latest",
    description="Investigates customer refund requests.",
    instruction=(
        "Investigate refund requests. Use lookup_order for recorded order facts, "
        "then delegate eligibility checks to refund_policy_specialist. "
        "Do not claim that a refund was issued."
    ),
    tools=[lookup_order],
    sub_agents=[policy_agent],
)

name identifies an agent. description advertises what it can handle, which helps another model distinguish it from peer agents. instruction instead guides that agent’s own behavior. A useful instruction states the task boundary, when to use each capability, prohibited actions, and the expected output.

For a Python function tool, ADK inspects the function name, docstring, type hints, parameters, and defaults to generate the schema presented to the model. Clear signatures and docstrings are therefore part of the routing interface, not decorative comments. See the ADK function tool documentation.

Declaring sub_agents makes the listed agents available for delegation. In ADK Python 2.0, ADK creates a delegation tool named after each subagent. Each subagent remains an agent: it can have its own model, instruction, and tools. The mode="single_turn" setting prevents user interaction and automatically returns the subagent’s result after one turn. Other collaboration modes have different interaction and return behavior. The official collaborative workflow guide documents those modes.

Finally, export the assembled tree as root_agent in agent.py so ADK tooling can discover the application entry point. The Python quickstart shows this project convention.

Key distinctions and trade-offs

A tool and a subagent are not interchangeable. Prefer a tool for an operation such as fetching an order, calculating tax, or submitting an approved action. Prefer a subagent when the delegated task benefits from a separate instruction, model, context boundary, or tool set.

An agent wrapped in AgentTool is another distinct design. The parent calls it like a tool and receives its answer back for further processing. By contrast, sub_agents declares a delegation relationship; control and return behavior depend on the subagent’s collaboration mode. See Agent-as-a-Tool.

Instructions guide model behavior but do not enforce security. A consequential tool must still validate arguments and authorization in code. ADK’s safety guidance recommends restricting the identity and permissions used against external systems so enforcement does not depend on the model’s decision. Expose only the tools that the agent needs, and separate read operations from write operations when their risks differ.

Architecture / decision scenario

A retailer needs an assistant to investigate refund requests. The root agent must retrieve live order facts, while policy interpretation changes by country and requires a focused prompt. The actual refund service is intentionally not available during investigation.

The architect attaches lookup_order to the coordinator because it is a narrow, authoritative data operation. The architect creates a policy subagent because eligibility is a reasoning task with its own instruction and policy lookup tool. The subagent uses single_turn mode because it needs no conversation with the customer and should return a bounded result. The coordinator then explains the decision. It cannot issue a refund because no refund-writing tool is present.

This composition separates facts, policy reasoning, and side effects. It also lets the team evaluate the policy specialist independently and choose a different model for it if its quality, latency, or cost requirements differ.

Common exam traps

• Treating the instruction as the capability: an agent cannot call an operation that is not registered as a tool.
• Treating instructions as an authorization boundary instead of enforcing permissions and validation in tool code.
• Confusing description, which advertises an agent for routing, with instruction, which guides the agent’s own behavior.
• Building a subagent for a narrow deterministic lookup that should be a tool.
• Assuming every registered tool is always called; the model decides whether a tool is relevant.
• Confusing a delegated subagent with an agent wrapped in AgentTool.
• Defining several agents but failing to connect them under the exported root_agent.

What to remember

• Assemble one coherent boundary: model, instruction, tools, and subagents must describe the same job.
• Use tools for bounded operations and subagents for bounded reasoning roles.
• Write precise names, descriptions, signatures, and docstrings because models use that metadata to select capabilities.
• Use tool-side controls for security; instructions are behavioral guidance.
• Export the connected agent tree as root_agent and evaluate its routing.

Knowledge check

References

• Google, Simple agents with LlmAgent
• Google, Function tools
• Google, Build collaborative agent teams
• Google, Python Quickstart for ADK
• Google, Safety and Security for AI Agents