feat(adk): declarative graph workflow agents for ADK Go 2.x

Makefile

@@ -368,6 +368,12 @@ build-byo-a2a: buildx-create
 	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) --build-arg BUILD_PACKAGE=core/test/byoa2a/main.go -t $(DOCKER_REGISTRY)/$(DOCKER_REPO)/byo-a2a:$(VERSION) -f go/Dockerfile ./go
 	$(DOCKER_PUSH) $(DOCKER_REGISTRY)/$(DOCKER_REPO)/byo-a2a:$(VERSION)
 
+.PHONY: build-workflow-agent
+build-workflow-agent: ## Build and push the generic BYO image for declarative workflow agents
+build-workflow-agent: buildx-create
+	$(DOCKER_BUILDER) $(DOCKER_BUILD_ARGS) $(TOOLS_IMAGE_BUILD_ARGS) --build-arg BUILD_PACKAGE=./adk/examples/declarative -t $(DOCKER_REGISTRY)/$(DOCKER_REPO)/workflow-agent:$(VERSION) -f go/Dockerfile ./go
+	$(DOCKER_PUSH) $(DOCKER_REGISTRY)/$(DOCKER_REPO)/workflow-agent:$(VERSION)
+
 .PHONY: build-claude-harness
 build-claude-harness: ## Build and push the native Claude Harness image
 build-claude-harness: buildx-create

docs/architecture/README.md

@@ -113,6 +113,8 @@ cleanup. Session lifecycle workers independently pause/suspend idle Actors.
 - [MCP](mcp.md)
 - [A2A agent tools](a2a-subagents.md)
 - [Human in the loop](human-in-the-loop.md)
+- [Declarative workflow agents](workflow-agents.md)
+- [Workflow design patterns](workflow-patterns.md)
 - [Token usage](usage-extension.md)
 - [Prompt resolution](prompt-templates.md)
 - [Telemetry](telemetry.md)

docs/architecture/a2a-subagents.md

@@ -33,6 +33,54 @@ tools:
 
 Tree resolution detects missing references and cycles before compilation.
 
+### Session isolation
+
+By default a subagent shares the parent's Session: the parent transfers control
+and the subagent answers in the same conversation history. `isolation: Isolated`
+on the binding changes the call model. The parent calls the subagent as a tool and
+receives its answer, and every call runs in a new conversation seeded with a copy
+of the parent's state:
+
+```yaml
+tools:
+  - subAgent:
+      name: reviewer
+      description: Review proposed changes before applying them.
+      isolation: Isolated
+      templateRef:
+        name: review-context
+```
+
+| | `Shared` (default) | `Isolated` |
+| --- | --- | --- |
+| Call model | The parent transfers the conversation | The parent calls a tool and gets a result |
+| History the subagent sees | The whole conversation | Only the request it was given |
+| Parallel calls | Share one conversation | One conversation each |
+| State | Shared | A copy; writes are not copied back |
+| Human input and approvals | Reach the person through the parent | Not possible |
+
+Use `Isolated` to fan out to the same subagent in parallel, to keep a long parent
+conversation out of the subagent's context, or to keep the subagent from seeing
+what the parent was told. The copy of the parent's state is what the subagent
+starts from, so do not keep values there that it should not see.
+
+The controller rejects an `Isolated` binding that cannot work, with
+`Compatible=False`:
+
+- Only the kagent and BYO Harnesses support it. Codex and Claude do not.
+- The subagent's MCP bindings cannot set `requireApproval`, and it is not offered
+  `ask_user`: its conversation ends with the tool call, so a request for a person
+  would never be answered.
+- It cannot be combined with STS token exchange. The exchanged token is cached by
+  session ID and an isolated subagent runs in a new session, so its MCP requests
+  would carry the caller's own credential instead. Plain token propagation works,
+  because the credential travels with the request.
+
+A subagent that is not isolated keeps its previous behavior and its revisions do
+not change. The same distinction exists for declarative workflows as
+`sub_agents` and `agent_tools`; see
+[Declarative workflow agents](workflow-agents.md#session-isolation).
+
 ## Dedicated agent tools
 
 Dedicated bindings would select an independently configured Agent with its own

docs/architecture/configuration-and-compilation.md

@@ -10,7 +10,10 @@ on each Agent that selects it.
 
 `AgentTemplate` describes what the agent does. It contains model configuration,
 description and prompt, MCP tool bindings, skills, plugins, and Shared
-subagent bindings (`tools[].subAgent`). Model configuration may be omitted for BYO images;
+subagent bindings (`tools[].subAgent`). A BYO root template may instead set
+`workflowFrom` to a ConfigMap-held declarative workflow document that the
+controller validates and delivers (see [Declarative workflow agents](workflow-agents.md#control-plane)).
+Model configuration may be omitted for BYO images;
 Agent compilation rejects managed harness combinations without one.
 
 `Agent` pairs one template and one Harness. The required `template` field selects
@@ -22,6 +25,8 @@ complete values, not overrides. References, including those inside inline specs,
 resolve in the Agent's namespace. The reusable resources have no binding to each other. Child templates are selected
 with `tools[].subAgent.templateRef` and compile under the parent Agent's Harness.
 Each subagent requires `templateRef` and shares the parent's runtime and Harness.
+It shares the parent's Session unless its binding sets `isolation: Isolated`; see
+[Session isolation](a2a-subagents.md#session-isolation).
 Dedicated `agentRef` bindings are deferred and are not part of the served API.
 
 The resource boundary does not grant authorization by itself. Kubernetes RBAC