Google Agent Development Kit（ADK）/ Gemini CLI

1. Introduction

1.1. Dual-Form Positioning

Google has two related but differently-positioned forms in this group of documents, and they must be discussed separately:

• Agent Development Kit (ADK): a code-first framework for production multi-agent systems, released on 2025-04-09 at Google Cloud Next 2025, open-source under Apache 2.0, covering four languages: Python, TypeScript, Go, and Java. Google's official positioning is "make agent development more like software development."
• Gemini CLI: an open-source agent tool for the terminal, released on 2025-06-25, Apache 2.0, based on the ReAct loop, directly competing with Claude Code and Codex CLI.

The relationship between the two is similar to Anthropic's Claude Agent SDK and Claude Code CLI — but not exactly parallel: ADK is a standalone framework, not a library wrapper around Gemini CLI.

ADK's key differentiator is that it simultaneously provides deterministic workflow agents and LLM-driven dynamic routing, rather than forcing users to choose between a "rigid pipeline" and "fully dynamic" approach.

1.2. Fact Sheet

1.3. Development Timeline

1.4. Position in the AI Harness System

ADK has the most complete six-layer coverage among the seven platforms in this group, with L4 (the Session / Memory / Artifact trio) and L5 (built-in evaluation framework) notably stronger than comparable SDKs.

But its positioning is still Agent Framework (a subset of Harness), not Agent Platform:

• It does not provide a UI tenant system, billing, or multi-tenant management (Dev UI is only for local debugging);
• The governance layer (L6) relies on callbacks and credential services, with no out-of-the-box RBAC or approval queues;
• Deployment and operations capabilities are carried by Google Cloud products such as Vertex AI / Cloud Run.

Gemini CLI, by contrast, belongs to "Harness's vertically-integrated form in the terminal scenario," adjacent to the AI IDE category in the parameter card.

2. Glossary

3. Feature Description

3.1. Five Agent Types and Two Orchestration Orientations

The value of this design is that a single framework provides both a "deterministic" and an "adaptive" gear, so teams can mix them by node importance. By contrast, the OpenAI Agents SDK has only one dynamic mechanism — handoff — while LangGraph is explicit-graph-first.

3.2. Tool Ecosystem

ADK's tools fall into five categories:

1. Pre-built tools: Google Search, Vertex AI Search, and a code-execution sandbox (Code Executor);
2. Custom function tools: plain Python / Go / Java / TS functions, for which the framework auto-generates the schema from type annotations and the docstring;
3. Long-running function tools: LongRunningFunctionTool, supporting start external task → return operation id → pause → resume from the application side;
4. MCP tools: connect any MCP server with a single McpToolset import;
5. Third-party framework adapters: consume LangChain and CrewAI tools directly via LangchainTool / CrewaiTool.

The fifth point is an easily underrated advantage of ADK: it does not require rebuilding the ecosystem from scratch, and can reuse existing framework assets.

A limitation noted in public reviews: some versions have a constraint that "a single agent can only attach one built-in tool," needs.

3.3. The Session / Memory / Artifact Trio

This is ADK's most complete part at the L4 layer, with a clear separation of duties among the three services:

The three are injected into agents via InvocationContext and Context; developers read and write state through context.state and persist artifacts through context.save_artifact().

This three-way split of "session state / long-term memory / artifacts" is closer to engineering reality than simply stuffing memory into a vector store.

3.4. Runner and Event-Driven Execution

ADK's most distinctive design is event-driven execution: every user message, tool call, and LLM response flows through the shared event bus as an event, uniformly scheduled by the Runner.

The benefits:

• Orchestration logic is cleanly separated from agent behavior;
• Execution traces are inspectable at every step;
• Streaming and real-time (Live) scenarios are natively supported (run_live, LiveRequestQueue).

RunConfig provides a rich set of runtime switches, including context_window_compression, max_llm_calls, history_config, and include_thoughts_from_other_agents.

3.5. Callback System

ADK has the broadest callback coverage among the platforms in this group:

Callbacks are the primary vehicle through which ADK assumes L6 governance responsibilities.

3.6. Built-in Evaluation Framework

ADK provides AgentEvaluator.evaluate(), characterized by double scoring:

1. Scores the final response quality;
2. Scores the step-by-step execution trace.

Combined with evalsets (predefined sets of test cases), this makes "run an evaluation on every commit, release only when the pass rate is met" a standard engineering practice. Third-party reviews consider this places ADK's abstraction level "close to right" for medium-complexity systems of 3~6 specialized agents.

There is also a known shortcoming: unit-test support for sub-agents is weak.

3.7. Deployment Paths and Dev UI

• Local: adk web / adk run / Dev UI debugging;
• Vertex AI Agent Engine: a managed runtime, deployable with a single command;
• Cloud Run / GKE / Docker: containerize and run on your own infrastructure;
• A2A server: the launcher/web/a2a sub-launcher provides A2A capabilities;
• REST API: the launcher/web/api sub-launcher.

3.8. Gemini CLI Capabilities and Issues

Capabilities:

• ReAct loop: read / write files, execute shell, web retrieval;
• Built-in tools: ls, read-file, read-many-files, find-files, grep, edit, write-file, shell, web-fetch, web-search, memoryTool;
• MCP server support (local and remote);
• Project-level GEMINI.md custom system prompt;
• Human confirmation: by default asks for confirmation before any potentially destructive operation (allow once / always allow / deny);
• Multi-layer sandboxing: macOS Seatbelt, Docker / Podman containers, proxies.

Publicly reported issues (compiled from users and reviews, not an official statement, marked [To be verified]):

4. Platform Architecture

图 4-1｜Google ADK 分层架构：从智能体定义到互操作部署

数据来源：基于本文分析绘制的示意图。

4.1. ADK Layered Architecture

┌──────────────────────────────────────────────────────────┐
│ 应用层：你的智能体定义                                      │
│  root_agent = LlmAgent / SequentialAgent / ParallelAgent /  │
│  LoopAgent（可任意层次嵌套）                                │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ ADK 运行时                                                 │
│  Runner（事件总线调度）                                     │
│  ├─ 编排层：transfer 动态路由 / 顺序 / 并行 / 循环           │
│  ├─ 回调层：agent / model / tool / error 八类回调            │
│  ├─ 上下文层：InvocationContext（state / branch / node_path）│
│  └─ 配置层：RunConfig（压缩 / max_llm_calls / history）      │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ 服务层（可替换后端）                                         │
│  SessionService（内存 / DB / Vertex AI）                    │
│  MemoryService（search_memory / add_session_to_memory）     │
│  ArtifactService（GCS / 本地，带版本）                       │
│  CredentialService（load_credential / save_credential）     │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ 工具层                                                     │
│  预构建（Google Search / Vertex AI Search / Code Exec）     │
│  自定义函数 · LongRunningFunctionTool · McpToolset          │
│  LangchainTool / CrewaiTool 适配器                          │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ 互操作与部署                                                │
│  A2A（Agent Card + JSON-RPC）· MCP · OpenAPI                │
│  本地 / Agent Engine / Cloud Run / GKE / Docker             │
└──────────────────────────────────────────────────────────┘

4.2. Event-Driven Execution Flow

1. The application invokes Runner, passing in the user message and session;
2. Runner creates an InvocationContext, assembling session / state / services;
3. Enters root_agent: triggers before_agent_callback;
4. If a model call is needed: triggers before_model_callback → calls the model → after_model_callback;
5. If the model returns tool calls: triggers before_tool_callback → executes the tool → after_tool_callback → the result is fed back as a new event;
6. If it is a workflow agent: schedules sub-agents per Sequential / Parallel / Loop semantics, each sub-agent recursively executing 3~5 steps;
7. Completion: triggers after_agent_callback; output_key can write the output into state for later nodes to read.

4.3. Gemini CLI Architecture

终端（交互式 / 非交互式脚本调用）
        │
Gemini CLI 主进程（Node.js 18+）
  ├─ ReAct 循环：推理 → 选工具 → 执行 → 观察 → 重复
  ├─ 内置工具：ls / read-file / find-files / grep / edit /
  │            write-file / shell / web-fetch / web-search
  ├─ MCP 客户端（本地 / 远程服务器）
  ├─ GEMINI.md 项目级指令加载
  ├─ 人工确认（允许一次 / 总是允许 / 拒绝）
  └─ 沙箱层（macOS Seatbelt / Docker / Podman / 代理）
        │
云端推理：Gemini 2.5 Pro（1M 上下文）

5. Harness Design

5.1. Six-Layer Capability Overview

5.2. L1 Context Engineering Layer

ADK's methods at L1 are relatively simple but adequate:

• include_contents controls whether historical content is brought into the current call;
• RunConfig.context_window_compression provides context-window compression configuration;
• global_instruction (cross-agent global instructions) and static_instruction (static instructions) are separated to avoid redundant injection;
• The Artifact mechanism externalizes large objects as artifacts, keeping only references in the context — consistent with Claude Agent SDK's "file system as context" approach.

Shortcomings: no progressive disclosure capability like Skills, and no retrieval/ranking primitives; RAG must rely on Vertex AI Search or be built in-house.

5.3. L2 Tools and Execution Layer

• Registration: typed functions are automatically schematized, keeping engineering overhead low;
• Sandboxing: provides a Code Executor sandbox (ADK) and multi-layer sandboxing (Gemini CLI: Seatbelt / Docker / Podman), making it the platform in this group with relatively clear sandbox capabilities;
• Interoperability: three protocols in parallel — MCP + A2A + OpenAPI;
• Ecosystem reuse: LangchainTool / CrewaiTool adapters can consume third-party framework tools.

Known limitations: public reviews mention the constraint that "a single agent can only attach one built-in tool," as well as strict file / directory conventions, needs.

5.4. L3 Orchestration and Control Layer

This is the layer where ADK diverges most clearly from the OpenAI Agents SDK.

ADK provides two orchestration orientations within a single framework:

This lets teams mix by node within a single system rather than committing wholesale to one end.

The tension between flexibility ↔ predictability is thereby partly resolved, but it also introduces two new problems:

1. Strong conventions, reduced flexibility: ADK has strict file / directory conventions (agents must be organized in a specific structure), which improves maintainability but reduces the freedom of improvised refactoring;
2. No explicit graph: until ADK 2.0's graph workflows land, complex conditional branches must still be expressed through hierarchical nesting, which is less readable than LangGraph's explicit graphs.

LoopAgent.max_iterations is the only hard iteration cap on the L3 side and can serve as a fallback against runaway loops.

5.5. L4 Memory and State Layer

Among the seven platforms in this group, ADK has the most complete L4 design:

This layering makes "what to remember" a configurable engineering decision rather than the black box of a single vector store.

5.6. L5 Evaluation and Observability Layer

ADK is one of the few approaches that make evaluation a built-in framework capability:

• AgentEvaluator.evaluate() performs double scoring on the final response and the step-by-step trace;
• evalsets support fixing evaluation into repeatably executable assets;
• The event-driven model naturally produces inspectable execution traces;
• Can integrate with Google Cloud Trace (inferred, not directly confirmed by official documentation, marked [To be verified]).

The "step-by-step trace scoring" item is especially critical — it means evaluation looks not only at whether the result is correct, but also at whether the process is reasonable. This is precisely Harness's essential value-add over bare model calls.

Known shortcoming: unit-test support for sub-agents is weak.

5.7. L6 Governance and Security Layer

The openness ↔ governance tension is most typified in A2A: A2A lets ADK agents interoperate with agents from other frameworks and organizations (Microsoft Azure AI Foundry, SAP Joule, Box, Auth0, and Zoom are all supported), but the Agent Card's capability-discovery mechanism is itself an attack surface — an agent that announces its capabilities is at the same time announcing an interface that can be probed. As of the retrieval date, A2A was at version 0.2, with limited maturity.

5.8. Concrete Manifestations of the Three Internal Tensions

6. Real-World Cases

Case One: Same-source validation with Google's internal products

Google has publicly stated that ADK is the framework underpinning its own products — including agents in Agentspace and the Customer Engagement Suite. The value here is "run it internally first, then open-source it": ADK does not solve a generic problem from a community wish-list, but the problems Google teams actually encountered (Vertex AI hosting, session continuity, cross-turn memory, Cloud Trace-integratable observability, and high-concurrency scaling). This statement comes from the official repository description, with no quantified data from independent third-party audits.

Case Two: Gemini CLI's scale validation

Within less than a year of release, Gemini CLI surpassed 100,000 GitHub stars, making it one of the fastest-growing projects among comparable terminal agents; its free quota (60 / minute, 1,000 / day, Gemini 2.5 Pro + 1M context) is called by Google "the largest quota in the industry." The star count comes from a third-party directory site, not an official figure, marked [To be verified].

Case Three: A2A ecosystem adoption

The A2A protocol is already supported by vendors including Microsoft Azure AI Foundry, SAP Joule, Box, Auth0, and Zoom. This is an early signal of the viability of cross-organization agent networks, but this capability "means less today than it will twelve months from now."

Parts for which no public quantified data was found: as of the retrieval date 2026-09-12, no third-party enterprise adoption data quantified against ADK was found (such as cost reduction, task success rate, or human-replacement rate). None of the above cases include verifiable quantitative metrics; this is stated honestly here and not padded out.

7. Summary

7.1. Strengths

1. Most complete six-layer coverage: among the seven platforms in this group, the only approach that reaches "strong" on both L4 and L5.
2. Dual orchestration orientations: deterministic workflows and dynamic routing mix within one framework, letting you choose the predictability gear per node.
3. Event-driven design: orchestration logic is separated from agent behavior, and traces are inspectable at every step.
4. Built-in evaluation: AgentEvaluator supports double scoring of the final response and the step-by-step trace, lowering the bar for engineering-level evaluation.
5. Multi-language: Python / TypeScript / Go / Java coverage across four languages, suiting teams with different tech stacks.
6. Ecosystem reuse: LangchainTool / CrewaiTool adapters avoid rebuilding the ecosystem from scratch.
7. Model-agnostic: optimized for Gemini but can connect other vendors' models via LiteLLM.

7.2. Weaknesses

1. Google Cloud binding bias: best-practice paths are heavily centered on Vertex AI / Cloud Run, decreasing appeal for infrastructure-agnostic projects.
2. Strict conventions: strict file / directory conventions reduce flexibility and room for improvised refactoring.
3. No explicit graph: until ADK 2.0's graph workflows land, complex branches are less readable than LangGraph.
4. Incomplete L6: no built-in RBAC, approval queues, or monetary-level cost guardrails.
5. Weak sub-agent unit testing: a shortcoming clearly identified in public reviews.
6. Gemini CLI stability controversy: issues such as rate limiting, silent degradation, overwriting edits, and fragile authentication are repeatedly reported (third-party accounts).

7.3. Applicability Boundary

7.4. Selection Recommendations

• If your team is already on Google Cloud and needs production-grade multi-agent orchestration, ADK is the most balanced choice in this group.
• If your team's top priority is the most complete observability and evaluation loop, consider LangGraph + LangSmith (see 04-langgraph.md), but ADK's evaluation is built into the framework at lower cost.
• If your team needs no-code / business-user participation in building, choose an Agent Platform (see 05-dify.md, 06-coze.md).
• Two things you must build yourself when adopting ADK: monetary-level budget guardrails and audit reports.

Information Gap Declaration

1. Exact version numbers per language: Python has third-party reports of v1.28.1, and Java / Go have 0.6.0 records, but these were not cross-checked item by item against official release pages, marked [To be verified].
2. ADK 2.0 graph workflows: only third-party articles mention them as "in research"; not confirmed by the official roadmap; their feature set and GA date are marked [To be verified].
3. The "one built-in tool per agent" constraint: from third-party reviews, not cross-verified with official documentation, marked [To be verified].
4. Cloud Trace integration: inferred from the event-driven model and the Google Cloud ecosystem, not directly confirmed by official documentation, marked [To be verified].
5. A2A's current version and security model: third parties say the protocol is at 0.2, not cross-checked against the Linux Foundation official repo; its authentication and authorization mechanisms were not specially researched.
6. Gemini CLI star count and issue reports: the star count comes from a third-party directory site; issues such as rate limiting / silent degradation / overwriting edits are compiled from users and reviews, all marked [To be verified].
7. Enterprise adoption quantified data: no verifiable third-party enterprise effectiveness data based on ADK was found; none was padded in.
8. Pricing details: the ADK framework itself is free, but the specific billing for Vertex AI Agent Engine and Gemini models was not obtained from official pricing during this research, marked [To be verified].

8. References

1. Agent Development Kit official documentation (Chinese site) — Google. https://adk.wiki
2. Agent Development Kit (Python) API Reference — Google. https://adk.dev/api-reference/python/
3. Agent Development Kit (ADK) for Go — pkg.go.dev. https://pkg.go.dev/google.golang.org/adk
4. Google ADK Review: The Agent Framework for Gemini — Awesome Agents. https://awesomeagents.ai/reviews/review-google-adk
5. What is Google ADK? The Agent Development Kit Explained for 2026 — FutureAGI. https://futureagi.com/blog/what-is-google-adk-2026/
6. Google unveils open-source Gemini CLI — Xinhua, 2025-06-26. https://www.news.cn/english/20250626/db3b06bf72604b5ab029616134bf59ed/c.html
7. Gemini CLI brings Google's AI agent to your terminal for free — 9to5Google, 2025-06-25. https://9to5google.com/2025/06/25/google-gemini-cli/
8. Gemini CLI Free Open-Source AI Agent — Belitsoft, 2025-06-25. https://belitsoft.com/news/gemini-cli-free-20250625
9. Google Open Source Blog (A2A donated to the Linux Foundation) — Google, 2025-06. https://opensource.googleblog.com/
10. R01-Overview research report (ADK orchestration primitives, A2A timeline) — internal research report for this project.
11. Project parameter card v1.0 (six-layer capability model and conceptual boundaries) — internal baseline document for this project.