Build and evaluate Google ADK Python agents with ak:google-adk-python

Use ak:google-adk-python to design or implement Python agents with Google's Agent Development Kit. The Skill covers single and multi-agent composition, workflow agents, tools and MCP, A2A, sessions, state, memory, artifacts, callbacks, plugins, evaluation, and deployment planning. Treat its API and model examples as tagged guidance that must be checked against the installed SDK.

Choose ak:google-adk-python for an ADK codebase

Use ak:google-adk-python when

• You are creating or changing a Python agent that uses Google ADK.
• You need sequential, parallel, loop, coordinator, or remote A2A patterns.
• You are integrating Python functions, long-running tools, MCP servers, state, artifacts, memory, callbacks, plugins, or tracing.
• You need an evaluation set, CLI test route, service wrapper, or deployment artifacts for Cloud Run, Vertex AI, or GKE.

Choose another workflow when

• You are still choosing an agent framework. Compare requirements and current primary documentation before committing to ADK.
• You need a provider-independent architecture only. Use ak:ask or ak:plan and keep the framework as a decision.
• You need to build an MCP server rather than consume one as an ADK tool. Use an MCP-building workflow.
• You only need deployment of an already verified application. Use ak:deploy or ak:devops with the provider boundary made explicit.

Prepare the SDK, provider, and project

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the active runtime and scope.
• Identify the installed google-adk version, Python version, package manager, project layout, model provider, model ID, region, authentication method, and target environment.
• Verify current ADK and provider documentation for every load-bearing API, command, model, service, quota, price, region, and deployment claim.
• Provide test credentials only through the project's approved secret mechanism. Keep production keys and customer data outside prompts and fixtures.
• Define tool permissions, data retention, session and memory boundaries, human approvals, evaluation criteria, latency or cost budget, and deployment authority.

The tagged Skill recommends Python 3.10 or newer and describes Python 3.11 as the preferred development baseline. It also uses this discovery convention:

my_agent/
├── __init__.py
└── agent.py

The source expects agent.py to expose root_agent or app, with the package initialization importing the agent definition. Confirm the current ADK loader contract before creating or restructuring files.

See Runtime adapters for broader target differences.

Run the Skill

Pass the agent outcome and operating boundaries in natural language. The Skill does not define its own mode flags; ADK CLI commands belong to the generated or existing project and must match its installed version.

/ak:google-adk-python "Add a Google ADK Python support agent to this existing package. Use the installed SDK, expose read-only account tools through a filtered MCPToolset, keep approval for any write, add a small eval set and unit tests, and do not call a paid model or deploy."

/ak:google-adk-python "Add a Google ADK Python support agent to this existing package. Use the installed SDK, expose read-only account tools through a filtered MCPToolset, keep approval for any write, add a small eval set and unit tests, and do not call a paid model or deploy."

$ak:google-adk-python "Add a Google ADK Python support agent to this existing package. Use the installed SDK, expose read-only account tools through a filtered MCPToolset, keep approval for any write, add a small eval set and unit tests, and do not call a paid model or deploy."

For a new project, specify whether the deliverable is architecture only, a local prototype, an evaluated service, or deployment-ready artifacts. Each outcome crosses a different dependency and authority boundary.

Select an agent and state pattern deliberately

Use an App when the verified SDK and project need plugins, event compaction, or custom lifecycle behavior. Do not add production infrastructure merely because a reference example shows it.

Observe an evidence-led ADK workflow

1. The run verifies the installed contract. It inspects package versions, imports, existing agents, configuration, provider setup, and current primary docs before choosing APIs or model IDs.
2. The run defines the agent boundary. It writes the responsibility, instructions, tools, data, session behavior, human approvals, and failure behavior before code.
3. The run selects composition and persistence. It chooses dynamic versus workflow agents and separates ephemeral state, artifacts, sessions, and long-term memory.
4. The run implements the smallest surface. It adds agent modules, typed and documented tools, filtered MCP access, callbacks or plugins only where the requirements need them.
5. The run tests without hiding model variance. It runs deterministic unit checks first, then approved integration and evaluation cases, recording model, provider, configuration, inputs, and results.
6. The run prepares deployment separately. Cloud Run, Vertex AI, GKE, secrets, scaling, observability, and rollback become an explicit deployment phase rather than an automatic continuation.

The tagged guide lists adk web <agents_dir>, adk run <agent_dir>, adk api_server <agents_dir>, and adk eval <agent> <evalset.json> as core development routes. Check adk --help and the installed package before using their exact argument shape.

Keep model, tool, data, and cloud effects explicit

• Default tools and fixtures to local, fake, read-only, or sandboxed behavior. Require confirmation immediately before sensitive or irreversible operations.
• Filter MCP tools to the smallest surface, validate arguments, set timeouts, and test error propagation and session behavior.
• Do not log prompts, tool arguments, model responses, traces, session state, memory, or artifacts without applying the project's privacy and retention policy.
• Treat every model name in the tagged references, including Gemini examples and non-Google provider claims, as point-in-time. Verify present availability, compatibility, pricing, and data terms.
• Ask separately before package installation, model calls, remote evaluation, cloud resource creation, secret changes, traffic exposure, deployment, or deletion.

Verify code, evaluations, and deployment evidence

A complete implementation should provide:

• The agent responsibility, composition, model and provider contract, tool list, approval gates, and persistence design.
• Exact files created or changed, including agent modules, tools, tests, eval sets, configuration, and any approved deployment artifacts.
• Installed SDK and Python versions, commands run, unit results, integration results, and evaluation criteria with pass and failure evidence.
• Evidence that tool filters, invalid inputs, timeouts, provider failures, session boundaries, artifact access, and human approvals behave as intended.
• Model-call count or available usage evidence, external services contacted, known cost exposure, skipped live checks, and remaining portability risk.
• For deployment, the target project and region, identity, secret references, health evidence, observability, scaling bounds, rollback route, and URL or endpoint only after an authorized deployment actually succeeds.

An evaluation score is not a production guarantee. Record the cases, judge or matcher, model configuration, sample size, and known blind spots.

Troubleshoot or continue

Continue with Testing, Web testing, or Deployment only when those next actions are in scope.

Know the current limits

• The Skill bundles guidance and examples, not google-adk, Python, a model, credentials, MCP servers, cloud CLIs, cloud resources, or an eval dataset.
• Several API, CLI, server endpoint, model, memory, plugin, and deployment examples are tied to the tagged source and may not match the installed SDK.
• Model-agnostic intent does not prove feature parity across providers or models.
• Stable and beta contain identical ak:google-adk-python Skill files for this release pair; provider and SDK behavior may still evolve independently.