From ed1c5671e0dcf30ec476c0b9fa0e0bb284870fad Mon Sep 17 00:00:00 2001 From: Ruben Koster Date: Mon, 10 Aug 2026 16:23:12 +0200 Subject: [PATCH 1/2] Add research note: Google ADK for Go --- research/adk-go.md | 145 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 research/adk-go.md diff --git a/research/adk-go.md b/research/adk-go.md new file mode 100644 index 0000000..7c5cd32 --- /dev/null +++ b/research/adk-go.md @@ -0,0 +1,145 @@ +--- +title: "Google Agent Development Kit (ADK) for Go — Graph-Based Agent Runtime" +author: Ruben Koster (@rkoster) +date: 2026-08-10 +tags: [orchestration, inter-agent-comms, observability-governance, runtime-lifecycle, ecosystem-survey] +cf_areas: [] +status: draft +sources: + - https://github.com/google/adk-go + - https://google.github.io/adk-docs/ + - https://google.github.io/adk-docs/get-started/go/ + - https://google.github.io/adk-docs/2.0/ + - https://google.github.io/adk-docs/a2a/intro/ + - https://google.github.io/adk-docs/deploy/agent-runtime/deploy/ + - https://google.github.io/adk-docs/tools-custom/mcp-tools/ + - https://google.github.io/adk-docs/observability/traces/ + - https://google.github.io/adk-docs/workflows/collaboration/ + - https://google.github.io/adk-docs/agents/workflow-agents/ + - https://google.github.io/adk-docs/agents/models/ +--- + +## Summary + +Agent Development Kit (ADK) for Go (`google/adk-go`) is Google's Apache-2.0, code-first +framework for building, evaluating, and deploying AI agents — a parallel, API-compatible +sibling to the original Python ADK (alongside Java, Kotlin, and TypeScript ports), developed +in lockstep with matching version numbers. ADK 2.0 (Go GA'd June 30, 2026, Python GA'd May 19, +2026) replaced the original hierarchical agent-executor model with a **graph-based Workflow +Runtime**, where agents, tools, and functions execute as nodes in an explicit workflow graph. +It is optimized for but not locked to Gemini, ships native MCP and A2A support, deep +OpenTelemetry GenAI-convention tracing, and one-command deployment to Google Cloud's Agent +Runtime (Vertex AI Agent Engine), Cloud Run, or GKE. Notably, kagent's Go engine (see +`kagent.md` in this research set) is built directly on ADK Go, making ADK Go a concrete +substrate choice already adopted by another CNCF-adjacent project surveyed here. + +## Key findings + +- **Governance, license, maturity**: Apache-2.0, maintained by Google under the `google` + GitHub org. Module path `google.golang.org/adk/v2` (Go 1.25+). ADK 2.0 is GA as of June 30, + 2026 for Go (Python GA'd ~6 weeks earlier), introducing graph-based workflows, parallel/loop + execution primitives, and human-in-the-loop tool confirmation as stable features — not + labeled alpha/preview. +- **Go and Python are lockstep siblings, not a lagging port**: both hit ADK 2.0 GA within + weeks of each other and ship the *same* breaking changes together (`BaseAgent`→`BaseNode`, + new `session.Event` fields, `session.NewEvent` requiring `context.Context` as first arg, + module path bump to `/v2`). Python retains a slightly larger catalog of pre-built + tools/integrations and some docs show Python-first examples with Go as a secondary tab, but + core API surface and release cadence are tightly synchronized — a different maturity + posture than, e.g., MAF's public-preview Go binding (see `microsoft-agent-framework.md`). +- **Graph-based Workflow Runtime (2.0's central change)**: `BaseAgent` now subclasses + `BaseNode`; agents, tools, and functions are evaluated as nodes in a Workflow Graph rather + than as standalone recursive executors. Legacy method overrides (`_run_async_impl`, custom + `Run`) are bypassed by the graph engine — custom logic must move into + `BeforeAgentCallback`/`AfterAgentCallback` hooks. This is architecturally close to + Microsoft Agent Framework's `executors`/`edges` workflow graph model, suggesting explicit + workflow-graph orchestration (vs. purely LLM-improvised control flow) is converging as an + industry default among major agent SDKs. +- **Two complementary orchestration layers**: (1) **template workflow agents** + (Sequential/Loop/Parallel) — deterministic control-flow agents that don't consult an LLM to + decide what runs next, now marked "superseded" by graph workflows in 2.0 but still + supported; and (2) **collaborative workflows**, where a coordinator `LlmAgent` delegates to + declared `SubAgents`, each auto-exposed to the coordinator as a callable tool. Three + delegation modes govern control-flow return semantics: `chat` (manual + `transfer_to_agent` handback), `task` (auto-return via `finish_task`, can ask clarifying + questions), and `single_turn` (no user interaction, supports parallel execution). Task-mode + agents must be leaves and run in an isolated session branch, invisible to sibling agents + until the parent collects results — a more structured isolation model than a shared + pub/sub topic (contrast with Dapr Agents' broadcast-based orchestration, `dapr-agents.md`). +- **Sessions/state as first-class, source-controllable concerns**: the runtime is built + around a `session.Service`/`Event` log, with documented support for "rewinding" and + "migrating" sessions, and layered context management (filtering irrelevant events, + summarizing old turns, lazy-loading artifacts, token tracking) rather than naive prompt + concatenation. Custom `session.Service` implementations backed by SQL/NoSQL must account + for the new 2.0 Event fields (`NodeInfo`, `Routes`, `RequestedInput`, `Output`, + `IsolationScope`) unless storing events as opaque JSON blobs. +- **Tool integration incl. MCP as both client and server**: a `tool.Tool` interface covers + function tools (`functiontool.New`), built-in tools (Google Search, Maps grounding via + `geminitool`), OpenAPI-derived tools, and MCP via `McpToolset` — ADK can *consume* external + MCP servers (stdio/SSE/streamable-HTTP) and *expose* ADK tools as an MCP server itself. Docs + explicitly call out MCP connection lifecycle/statefulness (session affinity, connection + cleanup, re-initialization after process restore) as an operational concern for scaled + deployments — a smaller-scope but analogous concern to Dapr Agents' child-workflow-per-MCP- + call durability guarantee. +- **First-class, bidirectional A2A support**: an `A2AServer` component exposes any ADK agent + as a network-accessible A2A service (see `a2a-protocol.md`), and `RemoteA2aAgent` consumes a + remote A2A-exposed agent as if it were a local sub-agent/tool, abstracting transport, auth, + and serialization. ADK's A2A layer preserves reasoning/thought traces, tracks long-running + tool calls across the network boundary, and passes file artifacts between agents. Docs + frame A2A vs. local sub-agents as an explicit tradeoff: network/cross-team/cross-language + boundaries → A2A; in-process modules → local sub-agents. +- **Deployment is "anywhere," with no built-in durable-execution substrate of its own**: + self-host on arbitrary infra, or one-command deploy (`adkgo deploy agentengine`) to Google + Cloud's Agent Runtime (Vertex AI Agent Engine), with Cloud Run and GKE also documented as + first-class targets (including a sidecar-MCP-server pattern for GKE). No mention of Dapr or + Temporal integration; the closest thing to a durability story is a `platform` package + providing pluggable time/UUID providers for "deterministic, replay-safe events," aimed at + external workflow engines rather than a built-in durable-execution guarantee. This mirrors + the pattern seen in Temporal's and MAF's notes: ADK treats durable execution as a substrate + to plug in, not a feature it ships. **kagent's Go engine is built directly on top of ADK + Go**, with kagent's own Kubernetes CRD/controller layer supplying the durability/scheduling + ADK itself doesn't provide (see `kagent.md`) — a concrete example of another project in this + research set choosing ADK Go as its agent-execution substrate. +- **Deep OpenTelemetry GenAI semantic-convention support**: implements OTel GenAI spans + (`invoke_agent`, `invoke_workflow`, `execute_tool`, `generate_content`) with attributes like + `gen_ai.operation.name`, `gen_ai.agent.name`, `gen_ai.usage.input_tokens` (see + `opentelemetry-genai.md`), emitting standard OTLP compatible with Jaeger, Grafana Tempo, + Datadog, and Cloud Trace, and propagating trace context across process boundaries so a tool + calling an external service links back to the agent's root trace. +- **Not Gemini-locked**: dedicated docs exist for Gemini, Gemma, Claude, OpenAI, Ollama, vLLM, + LiteLLM (multi-provider proxy), LiteRT-LM (on-device), Apigee AI Gateway, and Vertex-hosted + models, plus a "model routing" feature for dynamic model selection — though the Go + quickstart's own example wires up `gemini.NewModel` directly, reflecting first-party Gemini + SDK integration as the default path. + +## CF relevance + +ADK Go is a second, independent data point (after kagent, MAF, and Dapr Agents) that +graph/workflow-based orchestration with explicit sub-agent delegation modes is becoming the +standard shape for production agent frameworks — useful context regardless of whether CF ever +runs ADK-based agents directly. Its A2A-vs-local-sub-agent framing ("network boundary → A2A, +in-process → sub-agent") is a clean mental model CF could reuse when deciding where an +"agent" workload boundary should sit relative to CF's existing app/process boundary. That +kagent already builds its Go runtime on ADK Go also means any CF investigation of kagent +(flagged as a template for a "CF operator agent" in `kagent.md`) is implicitly an +investigation of ADK Go's architecture one layer down — worth keeping in mind so the two +notes aren't treated as fully independent options. + +## Open questions + +- ADK's `platform` package exposes deterministic time/UUID providers "for replay-safe + events" but ships no workflow-replay engine itself — would a CF-native agent runtime want + to pair ADK-style agent definitions with a separate durable-execution substrate (Temporal, + Dapr Workflows, or something CF-native), the same way kagent pairs it with Kubernetes CRDs? +- The `task`/`single_turn`/`chat` sub-agent isolation model (isolated session branches, + invisible to siblings until results are collected) is a stronger isolation default than + Dapr Agents' shared pub/sub topic — is this difference significant enough to matter for a + CF multi-agent trust/isolation model, or a superficial API difference over similar + underlying guarantees? +- How would ADK's MCP connection-affinity concerns (session affinity, cleanup on restart) + interact with CF's own instance placement/rebalancing, if ADK agents ran as CF app + instances? +- Given ADK Go and Python are kept in lockstep, is there a reason to standardize on the Go + implementation specifically for a CF-adjacent use case (e.g. matching CF's own Go-heavy + codebase, cf. kagent's Go-vs-Python cold-start tradeoff in `kagent.md`), or does the choice + come down purely to the language of the surrounding platform code? From e81016e00b9fbbdcdc2b4bb907997dc37b5af5d7 Mon Sep 17 00:00:00 2001 From: Ruben Koster Date: Mon, 10 Aug 2026 16:40:10 +0200 Subject: [PATCH 2/2] Refocus research note on ADK generally, not just the Go implementation Rename research/adk-go.md to research/google-adk.md and rewrite to cover Google's Agent Development Kit as a whole multi-language framework (Python/Go/Java/Kotlin/TypeScript kept in lockstep), rather than focusing on the Go implementation specifically. --- research/adk-go.md | 145 --------------------------------- research/google-adk.md | 180 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 180 insertions(+), 145 deletions(-) delete mode 100644 research/adk-go.md create mode 100644 research/google-adk.md diff --git a/research/adk-go.md b/research/adk-go.md deleted file mode 100644 index 7c5cd32..0000000 --- a/research/adk-go.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: "Google Agent Development Kit (ADK) for Go — Graph-Based Agent Runtime" -author: Ruben Koster (@rkoster) -date: 2026-08-10 -tags: [orchestration, inter-agent-comms, observability-governance, runtime-lifecycle, ecosystem-survey] -cf_areas: [] -status: draft -sources: - - https://github.com/google/adk-go - - https://google.github.io/adk-docs/ - - https://google.github.io/adk-docs/get-started/go/ - - https://google.github.io/adk-docs/2.0/ - - https://google.github.io/adk-docs/a2a/intro/ - - https://google.github.io/adk-docs/deploy/agent-runtime/deploy/ - - https://google.github.io/adk-docs/tools-custom/mcp-tools/ - - https://google.github.io/adk-docs/observability/traces/ - - https://google.github.io/adk-docs/workflows/collaboration/ - - https://google.github.io/adk-docs/agents/workflow-agents/ - - https://google.github.io/adk-docs/agents/models/ ---- - -## Summary - -Agent Development Kit (ADK) for Go (`google/adk-go`) is Google's Apache-2.0, code-first -framework for building, evaluating, and deploying AI agents — a parallel, API-compatible -sibling to the original Python ADK (alongside Java, Kotlin, and TypeScript ports), developed -in lockstep with matching version numbers. ADK 2.0 (Go GA'd June 30, 2026, Python GA'd May 19, -2026) replaced the original hierarchical agent-executor model with a **graph-based Workflow -Runtime**, where agents, tools, and functions execute as nodes in an explicit workflow graph. -It is optimized for but not locked to Gemini, ships native MCP and A2A support, deep -OpenTelemetry GenAI-convention tracing, and one-command deployment to Google Cloud's Agent -Runtime (Vertex AI Agent Engine), Cloud Run, or GKE. Notably, kagent's Go engine (see -`kagent.md` in this research set) is built directly on ADK Go, making ADK Go a concrete -substrate choice already adopted by another CNCF-adjacent project surveyed here. - -## Key findings - -- **Governance, license, maturity**: Apache-2.0, maintained by Google under the `google` - GitHub org. Module path `google.golang.org/adk/v2` (Go 1.25+). ADK 2.0 is GA as of June 30, - 2026 for Go (Python GA'd ~6 weeks earlier), introducing graph-based workflows, parallel/loop - execution primitives, and human-in-the-loop tool confirmation as stable features — not - labeled alpha/preview. -- **Go and Python are lockstep siblings, not a lagging port**: both hit ADK 2.0 GA within - weeks of each other and ship the *same* breaking changes together (`BaseAgent`→`BaseNode`, - new `session.Event` fields, `session.NewEvent` requiring `context.Context` as first arg, - module path bump to `/v2`). Python retains a slightly larger catalog of pre-built - tools/integrations and some docs show Python-first examples with Go as a secondary tab, but - core API surface and release cadence are tightly synchronized — a different maturity - posture than, e.g., MAF's public-preview Go binding (see `microsoft-agent-framework.md`). -- **Graph-based Workflow Runtime (2.0's central change)**: `BaseAgent` now subclasses - `BaseNode`; agents, tools, and functions are evaluated as nodes in a Workflow Graph rather - than as standalone recursive executors. Legacy method overrides (`_run_async_impl`, custom - `Run`) are bypassed by the graph engine — custom logic must move into - `BeforeAgentCallback`/`AfterAgentCallback` hooks. This is architecturally close to - Microsoft Agent Framework's `executors`/`edges` workflow graph model, suggesting explicit - workflow-graph orchestration (vs. purely LLM-improvised control flow) is converging as an - industry default among major agent SDKs. -- **Two complementary orchestration layers**: (1) **template workflow agents** - (Sequential/Loop/Parallel) — deterministic control-flow agents that don't consult an LLM to - decide what runs next, now marked "superseded" by graph workflows in 2.0 but still - supported; and (2) **collaborative workflows**, where a coordinator `LlmAgent` delegates to - declared `SubAgents`, each auto-exposed to the coordinator as a callable tool. Three - delegation modes govern control-flow return semantics: `chat` (manual - `transfer_to_agent` handback), `task` (auto-return via `finish_task`, can ask clarifying - questions), and `single_turn` (no user interaction, supports parallel execution). Task-mode - agents must be leaves and run in an isolated session branch, invisible to sibling agents - until the parent collects results — a more structured isolation model than a shared - pub/sub topic (contrast with Dapr Agents' broadcast-based orchestration, `dapr-agents.md`). -- **Sessions/state as first-class, source-controllable concerns**: the runtime is built - around a `session.Service`/`Event` log, with documented support for "rewinding" and - "migrating" sessions, and layered context management (filtering irrelevant events, - summarizing old turns, lazy-loading artifacts, token tracking) rather than naive prompt - concatenation. Custom `session.Service` implementations backed by SQL/NoSQL must account - for the new 2.0 Event fields (`NodeInfo`, `Routes`, `RequestedInput`, `Output`, - `IsolationScope`) unless storing events as opaque JSON blobs. -- **Tool integration incl. MCP as both client and server**: a `tool.Tool` interface covers - function tools (`functiontool.New`), built-in tools (Google Search, Maps grounding via - `geminitool`), OpenAPI-derived tools, and MCP via `McpToolset` — ADK can *consume* external - MCP servers (stdio/SSE/streamable-HTTP) and *expose* ADK tools as an MCP server itself. Docs - explicitly call out MCP connection lifecycle/statefulness (session affinity, connection - cleanup, re-initialization after process restore) as an operational concern for scaled - deployments — a smaller-scope but analogous concern to Dapr Agents' child-workflow-per-MCP- - call durability guarantee. -- **First-class, bidirectional A2A support**: an `A2AServer` component exposes any ADK agent - as a network-accessible A2A service (see `a2a-protocol.md`), and `RemoteA2aAgent` consumes a - remote A2A-exposed agent as if it were a local sub-agent/tool, abstracting transport, auth, - and serialization. ADK's A2A layer preserves reasoning/thought traces, tracks long-running - tool calls across the network boundary, and passes file artifacts between agents. Docs - frame A2A vs. local sub-agents as an explicit tradeoff: network/cross-team/cross-language - boundaries → A2A; in-process modules → local sub-agents. -- **Deployment is "anywhere," with no built-in durable-execution substrate of its own**: - self-host on arbitrary infra, or one-command deploy (`adkgo deploy agentengine`) to Google - Cloud's Agent Runtime (Vertex AI Agent Engine), with Cloud Run and GKE also documented as - first-class targets (including a sidecar-MCP-server pattern for GKE). No mention of Dapr or - Temporal integration; the closest thing to a durability story is a `platform` package - providing pluggable time/UUID providers for "deterministic, replay-safe events," aimed at - external workflow engines rather than a built-in durable-execution guarantee. This mirrors - the pattern seen in Temporal's and MAF's notes: ADK treats durable execution as a substrate - to plug in, not a feature it ships. **kagent's Go engine is built directly on top of ADK - Go**, with kagent's own Kubernetes CRD/controller layer supplying the durability/scheduling - ADK itself doesn't provide (see `kagent.md`) — a concrete example of another project in this - research set choosing ADK Go as its agent-execution substrate. -- **Deep OpenTelemetry GenAI semantic-convention support**: implements OTel GenAI spans - (`invoke_agent`, `invoke_workflow`, `execute_tool`, `generate_content`) with attributes like - `gen_ai.operation.name`, `gen_ai.agent.name`, `gen_ai.usage.input_tokens` (see - `opentelemetry-genai.md`), emitting standard OTLP compatible with Jaeger, Grafana Tempo, - Datadog, and Cloud Trace, and propagating trace context across process boundaries so a tool - calling an external service links back to the agent's root trace. -- **Not Gemini-locked**: dedicated docs exist for Gemini, Gemma, Claude, OpenAI, Ollama, vLLM, - LiteLLM (multi-provider proxy), LiteRT-LM (on-device), Apigee AI Gateway, and Vertex-hosted - models, plus a "model routing" feature for dynamic model selection — though the Go - quickstart's own example wires up `gemini.NewModel` directly, reflecting first-party Gemini - SDK integration as the default path. - -## CF relevance - -ADK Go is a second, independent data point (after kagent, MAF, and Dapr Agents) that -graph/workflow-based orchestration with explicit sub-agent delegation modes is becoming the -standard shape for production agent frameworks — useful context regardless of whether CF ever -runs ADK-based agents directly. Its A2A-vs-local-sub-agent framing ("network boundary → A2A, -in-process → sub-agent") is a clean mental model CF could reuse when deciding where an -"agent" workload boundary should sit relative to CF's existing app/process boundary. That -kagent already builds its Go runtime on ADK Go also means any CF investigation of kagent -(flagged as a template for a "CF operator agent" in `kagent.md`) is implicitly an -investigation of ADK Go's architecture one layer down — worth keeping in mind so the two -notes aren't treated as fully independent options. - -## Open questions - -- ADK's `platform` package exposes deterministic time/UUID providers "for replay-safe - events" but ships no workflow-replay engine itself — would a CF-native agent runtime want - to pair ADK-style agent definitions with a separate durable-execution substrate (Temporal, - Dapr Workflows, or something CF-native), the same way kagent pairs it with Kubernetes CRDs? -- The `task`/`single_turn`/`chat` sub-agent isolation model (isolated session branches, - invisible to siblings until results are collected) is a stronger isolation default than - Dapr Agents' shared pub/sub topic — is this difference significant enough to matter for a - CF multi-agent trust/isolation model, or a superficial API difference over similar - underlying guarantees? -- How would ADK's MCP connection-affinity concerns (session affinity, cleanup on restart) - interact with CF's own instance placement/rebalancing, if ADK agents ran as CF app - instances? -- Given ADK Go and Python are kept in lockstep, is there a reason to standardize on the Go - implementation specifically for a CF-adjacent use case (e.g. matching CF's own Go-heavy - codebase, cf. kagent's Go-vs-Python cold-start tradeoff in `kagent.md`), or does the choice - come down purely to the language of the surrounding platform code? diff --git a/research/google-adk.md b/research/google-adk.md new file mode 100644 index 0000000..28b1c61 --- /dev/null +++ b/research/google-adk.md @@ -0,0 +1,180 @@ +--- +title: "Google Agent Development Kit (ADK) — Graph-Based, Multi-Language Agent Framework" +author: Ruben Koster (@rkoster) +date: 2026-08-10 +tags: [orchestration, inter-agent-comms, observability-governance, runtime-lifecycle, ecosystem-survey] +cf_areas: [] +status: draft +sources: + - https://github.com/google/adk-python + - https://github.com/google/adk-go + - https://google.github.io/adk-docs/ + - https://google.github.io/adk-docs/2.0/ + - https://google.github.io/adk-docs/get-started/about/ + - https://google.github.io/adk-docs/a2a/intro/ + - https://google.github.io/adk-docs/deploy/agent-runtime/deploy/ + - https://google.github.io/adk-docs/tools-custom/mcp-tools/ + - https://google.github.io/adk-docs/observability/traces/ + - https://google.github.io/adk-docs/workflows/collaboration/ + - https://google.github.io/adk-docs/agents/workflow-agents/ + - https://google.github.io/adk-docs/agents/models/ + - https://google.github.io/adk-docs/evaluate/ +--- + +## Summary + +Google's Agent Development Kit (ADK) is an Apache-2.0, code-first framework for building, +evaluating, and deploying AI agents — originally built internally at Google to power agentic +products (Agentspace and other Gemini-powered agent surfaces) before being open-sourced, and +now maintained as a family of first-party, API-compatible implementations (Python — flagship, +Go, Java, Kotlin, TypeScript) kept in lockstep under the `google` GitHub org. ADK 2.0 (Python +GA'd May 19, 2026, other languages following within weeks) replaced the original hierarchical +agent-executor model with a **graph-based Workflow Runtime**, paired with a structured **Task +API** for agent-to-agent delegation. Beyond agent definition, ADK bundles broad tool +integration (function tools, OpenAPI, MCP client+server), first-class bidirectional A2A +protocol support, built-in evaluation tooling (trajectory + response-quality scoring), and +deep OpenTelemetry GenAI-convention observability — with deployment paths from self-hosted +containers to Google Cloud's Agent Runtime, Cloud Run, and GKE. + +## Key findings + +- **Origin, license, governance**: ADK is Google's own internal agent framework — used for + products like Agentspace and other Gemini-powered agent surfaces — subsequently open-sourced + under Apache-2.0. It lives entirely under the `google` GitHub org (`adk-python`, `adk-go`, + `adk-java`, `adk-kotlin`, `adk-js`, plus `adk-docs`, `adk-web`, and `adk-samples`), not a + third-party or community-donated project. `adk-python` alone has ~21k GitHub stars and a + roughly bi-weekly release cadence. +- **Multi-language strategy is first-party and lockstep, not community ports**: Python, Go, + Java, Kotlin, and TypeScript are all maintained by Google in the same org, share the same + version numbers, and hit the ADK 2.0 GA milestone within weeks of each other, shipping the + same breaking API changes together. The docs site presents all languages side-by-side in + code tabs rather than treating any as secondary — though Python retains the largest catalog + of pre-built tools/integrations and is generally the "docs-first" language, and some + deploy/integration guides show Python examples with other languages as secondary tabs. This + is a notably different maturity posture than, e.g., Microsoft Agent Framework's + public-preview Go binding (see `microsoft-agent-framework.md`). +- **Core primitives**: an `Agent` (typically an `LlmAgent`, defined by model + instruction + + tools) and a `Workflow` (orchestrates agents/tasks as a graph), with supporting concepts — + `Tool`, `Callback`, `Session`/`State`/`Event` (conversation context and history), `Memory` + (cross-session long-term recall, distinct from session state), `Artifact` (file/binary + management), code execution, and ReAct-style planning — all coordinated by a `Runner` + engine. +- **ADK 2.0's central architectural shift is a graph-based Workflow Runtime**: agents, tools, + and functions now execute as nodes in an explicit `Workflow` graph (edges like + `("START", agentA, agentB)`) supporting routing, fan-out/fan-in, loops, retries, state + management, dynamic nodes, human-in-the-loop pauses, and nested workflows — replacing the + older recursive agent-executor model where control flow was implicit in code (custom logic + now has to move into `BeforeAgentCallback`/`AfterAgentCallback` hooks rather than method + overrides). This is paired with a new **Task API** for structured agent-to-agent delegation. + The shift is architecturally close to Microsoft Agent Framework's `executors`/`edges` graph + model, suggesting explicit workflow-graph orchestration (vs. purely LLM-improvised control + flow) is converging as an industry default among major agent SDKs. +- **Two complementary orchestration layers coexist**: (1) **template workflow agents** + (`SequentialAgent`, `ParallelAgent`, `LoopAgent`) — deterministic control-flow agents that + don't consult an LLM to decide what runs next, now positioned as "superseded" by graph + workflows in 2.0 but still supported; and (2) **collaborative workflows**, where a + coordinator `LlmAgent` delegates to declared sub-agents, each auto-exposed to the + coordinator as a callable tool (`AgentTool`). Three delegation modes govern control-flow + return semantics: `chat` (manual `transfer_to_agent` handback, full user interaction), + `task` (auto-return via `finish_task`, can still ask clarifying questions), and + `single_turn` (no user interaction, supports parallel execution). Task-mode agents must be + leaves and run in an isolated session branch, invisible to sibling agents until the parent + collects results — a more structured isolation model than a shared pub/sub topic (contrast + with Dapr Agents' broadcast-based orchestration, `dapr-agents.md`). +- **Sessions/state as first-class, source-controllable concerns**: the runtime is built + around a `Session`/`Event` log, with documented support for "rewinding" and "migrating" + sessions, and layered context management (filtering irrelevant events, summarizing old + turns, lazy-loading artifacts, token tracking) rather than naive prompt concatenation. + Custom session-store implementations backed by SQL/NoSQL must account for new 2.0 Event + fields (node info, routes, requested input, output, isolation scope) unless storing events + as opaque JSON blobs. +- **Broad tool integration, including MCP as both client and server**: `FunctionTool` for + custom functions, `AgentTool` (agents used as tools), built-in tools (Google Search, code + execution, Maps grounding), OpenAPI-derived tools, and MCP support in both directions — ADK + agents can consume external MCP servers (stdio/SSE/streamable-HTTP) and be exposed as an MCP + server themselves. Docs explicitly call out MCP connection lifecycle/statefulness (session + affinity, connection cleanup, re-initialization after process restore) as an operational + concern for scaled deployments — a smaller-scope but analogous concern to Dapr Agents' + child-workflow-per-MCP-call durability guarantee. +- **First-class, bidirectional A2A protocol support**: an A2A server component exposes any + ADK agent as a network-accessible A2A service (see `a2a-protocol.md`), and a remote-agent + component consumes a remote A2A-exposed agent as if it were a local sub-agent/tool, + abstracting transport, auth, and serialization while preserving reasoning/thought traces, + tracking long-running tool calls across the network boundary, and passing file artifacts + between agents. Docs frame A2A vs. local sub-agents as an explicit tradeoff: + network/cross-team/cross-language boundaries → A2A; in-process modules → local sub-agents. +- **Deployment is "anywhere," with no bundled durable-execution engine**: self-host on + arbitrary infrastructure, or one-command deploy to Google Cloud's Agent Runtime (Vertex AI + Agent Engine), Cloud Run, or GKE — all inheriting managed infra, auth, Cloud Trace + observability, and security without code changes. ADK ships no durable-execution/ + crash-recovery substrate of its own; it exposes primitives (deterministic time/UUID + providers "for replay-safe events") aimed at pairing with an external durability layer + rather than providing one itself. This mirrors the pattern seen in Temporal's and MAF's + notes: ADK treats durable execution as a substrate to plug in, not a feature it ships. +- **Adoption signal — kagent builds on ADK**: kagent (a CNCF-adjacent Kubernetes-native agent + platform, covered separately in `kagent.md`) builds its Go execution engine directly on top + of ADK, using it as the agent-execution substrate while layering its own Kubernetes + CRD/controller model on top for scheduling and durability — a concrete example of ADK being + adopted as infrastructure by another agent-orchestration project, not only used directly by + end developers. +- **Deep OpenTelemetry GenAI semantic-convention observability**: implements OTel GenAI spans + (`invoke_agent`, `invoke_workflow`, `execute_tool`, `generate_content`) with attributes like + `gen_ai.operation.name`, `gen_ai.agent.name`, `gen_ai.usage.input_tokens` (see + `opentelemetry-genai.md`), emitting standard OTLP compatible with Jaeger, Grafana Tempo, + Datadog, and Cloud Trace, and propagating trace context across process boundaries so a tool + calling an external service links back to the agent's root trace. +- **Not Gemini-locked, though Gemini-optimized by default**: dedicated docs/adapters exist for + Gemini, Gemma, Claude, OpenAI, Ollama, vLLM, LiteLLM (multi-provider proxy), LiteRT-LM + (on-device), and Apigee AI Gateway, plus a "model routing" feature for dynamic model + selection at runtime — the model abstraction is the extensibility point, though quickstart + examples across languages default to a Gemini model out of the box. +- **Built-in evaluation tooling (ADK Eval) is a notable differentiator**: a schema-backed + evaluation framework distinguishing **trajectory evaluation** (comparing actual vs. expected + tool-call/step sequences) from **final-response evaluation**, supporting both lightweight + per-file "unit tests" and larger multi-session "evalsets," a dedicated CLI eval command, + test-framework integration, a web UI for capturing/editing eval cases with a trace-view + debugger, and a conformance-test mode that records baseline LLM/tool interactions and + replays them to catch behavioral drift. Eleven built-in criteria are provided (tool- + trajectory match, ROUGE-based and LLM-judged response match, rubric-based quality/tool-use + judging, hallucination/safety scoring, multi-turn task success, etc.), several requiring the + Vertex Gen AI Evaluation Service API. + +## CF relevance + +ADK is another independent data point (alongside kagent, Microsoft Agent Framework, and Dapr +Agents) that graph/workflow-based orchestration with explicit sub-agent delegation modes is +converging as the standard shape for production agent frameworks — useful context regardless +of whether CF ever runs ADK-based agents directly. Its A2A-vs-local-sub-agent framing +("network boundary → A2A, in-process → sub-agent") is a clean mental model CF could reuse when +deciding where an "agent" workload boundary should sit relative to CF's existing app/process +boundary. ADK's built-in evaluation/conformance tooling is also a distinctive feature not +mirrored elsewhere in this research set — worth flagging as a separate concern from runtime +orchestration: how would a CF-hosted agent platform support pre-deployment behavioral testing +and drift detection, independent of which orchestration framework produced the agent? Finally, +since kagent already builds its runtime on ADK, any CF investigation of kagent (flagged as a +template for a "CF operator agent" in `kagent.md`) is implicitly an investigation of ADK's +architecture one layer down — worth keeping in mind so the two notes aren't treated as fully +independent options. + +## Open questions + +- ADK exposes deterministic time/UUID providers "for replay-safe events" but ships no + workflow-replay engine itself — would a CF-native agent runtime want to pair ADK-style + agent definitions with a separate durable-execution substrate (Temporal, Dapr Workflows, or + something CF-native), the same way kagent pairs it with Kubernetes CRDs? +- The `task`/`single_turn`/`chat` sub-agent isolation model (isolated session branches, + invisible to siblings until results are collected) is a stronger isolation default than Dapr + Agents' shared pub/sub topic — is this difference significant enough to matter for a CF + multi-agent trust/isolation model, or a superficial API difference over similar underlying + guarantees? +- How would ADK's MCP connection-affinity concerns (session affinity, cleanup on restart) + interact with CF's own instance placement/rebalancing, if ADK agents ran as CF app + instances? +- Is ADK's built-in evaluation/conformance-testing model (trajectory + response-quality + scoring, replay-based drift detection) something a CF agent platform should surface as a + platform-level capability (akin to a CI gate), or is that squarely an application-level + concern regardless of which framework produced the agent? +- Given ADK's language implementations are kept in lockstep, does the choice between them for + a CF-adjacent use case (e.g. Go, to match CF's own codebase — see kagent's Go-vs-Python + cold-start tradeoff in `kagent.md`) come down purely to ecosystem fit with the surrounding + platform, or are there framework-level differences worth weighing?