Google Adk

Google Agent Development Kit (ADK)

This skill covers building production-grade AI agents with Google's Agent Development Kit (ADK) for Python, including agent composition, tool design, session/state/memory management, artifacts, evaluation, and deployment.

Workflow for Building an ADK Agent

1. Define the agent — Create an LlmAgent (or Agent) with a clear name, model, instruction, and description. Keep the instruction focused on one job.
2. Author tools — Write plain Python functions with type hints and docstrings, or wrap existing APIs with FunctionTool. Validate all inputs before side effects.
3. Compose multi-agent systems — For complex workflows, split responsibility across sub-agents and use SequentialAgent, ParallelAgent, or LoopAgent for deterministic orchestration, or delegate via sub_agents for LLM-driven routing.
4. Wire up session and state — Choose a SessionService (in-memory for dev, DatabaseSessionService or Vertex AI-managed for production) and use session.state for conversation-scoped data.
5. Add memory (optional) — Configure a MemoryService for cross-session recall when the agent needs to remember facts between separate conversations.
6. Handle artifacts (optional) — Configure an ArtifactService when the agent generates or receives files, images, or other binary outputs.
7. Run locally — Use adk web, adk run, or the Runner API to exercise the agent against a Session.
8. Evaluate — Write .evalset.json test cases and run adk eval to check tool-call trajectories and response quality against regressions.
9. Deploy — Package the agent for Vertex AI Agent Engine, Cloud Run, or GKE, and separate dev/staging/prod configuration.

Agent Design

• Keep each agent focused on a single clear goal, persona, and tool set — avoid one agent that tries to do everything.
• Use LlmAgent for flexible, reasoning-driven behavior and workflow agents (SequentialAgent, ParallelAgent, LoopAgent) for deterministic orchestration that doesn't need an LLM to decide the next step.
• Write instructions that define task boundaries, tool-use rules ("always call lookup_order before answering order questions"), and escalation behavior ("if you cannot resolve the issue, transfer to human_handoff_agent").
• Split multi-agent systems by responsibility (e.g., a "triage" agent, a "billing" agent, a "technical support" agent) rather than by implementation convenience.
• Keep the model name configurable (environment variable or config file) so it can be swapped across gemini-2.0-flash, gemini-2.5-pro, or other supported models without code changes.
• Use output_schema (a Pydantic model) when the agent's final response must be structured data consumed by other code.

Tools

• Give tools narrow, typed inputs and outputs — a single function should do one thing, with a docstring the LLM uses to decide when to call it.
• Validate tool arguments before performing any side effect (writes, external calls, payments).
• Keep secrets, credentials, and privileged API keys out of agent instructions and prompts; inject them at the tool implementation layer instead.
• Handle tool errors explicitly and return actionable failure messages (e.g., {"status": "error", "message": "order_id not found"}) rather than raising unhandled exceptions that break the agent loop.
• Be aware of ADK tool limitations — some built-in tools (e.g., google_search, code_execution) cannot be combined with other tools on the same agent; delegate to a dedicated sub-agent instead.
• Prefer FunctionTool for custom Python logic, AgentTool to let one agent call another agent as a tool, and built-in tools (google_search, BuiltInCodeExecutor) only when their constraints fit the use case.

Example: Defining an Agent with Tools

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.runners import InMemoryRunner
from google.genai import types


def get_order_status(order_id: str) -> dict:
    """Look up the current status of a customer order.

    Args:
        order_id: The unique identifier of the order, e.g. "ord-12345".

    Returns:
        A dict with 'status' ('found' or 'error') and either 'state'
        and 'updated_at', or an error 'message'.
    """
    if not order_id or not order_id.startswith("ord-"):
        return {"status": "error", "message": "invalid order_id format"}

    # In production this would call a real order service.
    orders = {"ord-12345": {"state": "shipped", "updated_at": "2026-08-30T10:00:00Z"}}
    order = orders.get(order_id)
    if order is None:
        return {"status": "error", "message": f"no order found for {order_id}"}
    return {"status": "found", **order}


root_agent = Agent(
    name="order_support_agent",
    model="gemini-2.0-flash",
    description="Answers customer questions about order status.",
    instruction=(
        "You help customers check their order status. "
        "Always call get_order_status before answering an order question. "
        "If the tool returns an error, apologize and ask the customer to "
        "double-check their order ID. Never invent an order status."
    ),
    tools=[FunctionTool(func=get_order_status)],
)


async def main() -> None:
    runner = InMemoryRunner(agent=root_agent, app_name="order_support")
    session = await runner.session_service.create_session(
        app_name="order_support", user_id="user-1"
    )
    message = types.Content(
        role="user", parts=[types.Part(text="What's the status of ord-12345?")]
    )
    async for event in runner.run_async(
        user_id="user-1", session_id=session.id, new_message=message
    ):
        if event.content and event.content.parts:
            for part in event.content.parts:
                if part.text:
                    print(part.text)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

Sessions, State, and Memory

• Use session.state for current-conversation data — user preferences discovered mid-conversation, counters, intermediate results.
• Use a MemoryService for cross-session recall and retrieval (facts that should persist after the session ends and be searchable in future sessions).
• Keep state values small and serializable (strings, numbers, small dicts/lists) — never store large files or binary payloads directly in session state.
• Make state keys stable and documented; use prefixes (user:, app:, temp:) to scope state lifetime consistently across the app.
• For production, use DatabaseSessionService or the managed Vertex AI session service instead of InMemorySessionService, which loses all state on process restart.

Artifacts

• Use artifacts for generated files, uploaded files, reports, images, audio, and any other binary data — not session state.
• Configure an ArtifactService (e.g., InMemoryArtifactService for dev, GcsArtifactService for production) on the Runner before relying on artifact operations like save_artifact or load_artifact.
• Version artifact filenames intentionally (ADK auto-increments versions per filename) and avoid overwriting semantically different outputs under the same name.
• Store only references or short summaries in session state when the full content belongs in an artifact — e.g., keep report_v2.pdf as the artifact and "generated report v2" as the state note.

Evaluation and Deployment

• Add .evalset.json test cases covering tool-call trajectories (which tools were called, in what order, with what arguments) and final response quality.
• Run adk eval <agent_module> <eval_set_file> in CI to catch prompt regressions before merging instruction changes.
• Use ADK's trace and event logs (adk web's trace view, or Runner events) to debug agent decisions — inspect which tool was called, what arguments were passed, and what the model saw.
• Keep local development, staging, and production configuration separate (different SessionService/ArtifactService backends, different API keys, different model tiers).
• Add observability for latency, tool failures, token use, and handoff failures — wrap tool functions with timing/logging decorators and export metrics to your existing monitoring stack.
• Deploy to Vertex AI Agent Engine for a managed, autoscaled runtime, or containerize with adk deploy cloud_run / a custom Dockerfile for Cloud Run or GKE when more control over the environment is needed.

Common Mistakes

• Making one agent responsible for every workflow instead of decomposing into focused sub-agents.
• Letting tools accept arbitrary shell, SQL, or HTTP input without validation, which turns a tool call into an injection vector.
• Relying on prompt text for access control — instructions like "never reveal other users' data" are guidance, not enforcement; check permissions in tool code.
• Hiding important side effects (payments, deletions, external notifications) behind generic tool names like process or handle — name tools for what they actually do.
• Forgetting to set output_key or output_schema when downstream code depends on a structured final response, leading to fragile string parsing.
• Skipping evals on instruction changes — a rephrased prompt can silently change which tools the model chooses to call.