Files
solution_architecture_agent/docs/adr/0003-langgraph-holds-state-adk-agents-reason.md
Jonathan Boniface c84dbdea20 feat: the solution architecture agent on the shared Execution engine
The reference agent's subject, cloud solution architecture, as an agent in
the operating model agent's pattern: the Execution engine (from
orchestration_engine) and one Workflow in app/solution_architecture,
built for the settings and provider bundle by assembly.workflow_for.

Copied from gcp_solution_architecture_agent at 8b397cd without its own
engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts
and evaluation datasets. The image takes the engine from a named build
context and installs Terraform. It is called through the Orchestration
engine, and its files are what the operating model agent digests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 19:49:28 +01:00

2.7 KiB

status, supersedes
status supersedes
accepted ADR-0001

LangGraph holds Execution state; ADK agents reason and act

An Execution is a hierarchy of ReAct agents shaped by the dependencies between Deliverables (ADR-0002).

  • LangGraph holds the Execution. A LangGraph StateGraph holds the dependency graph and each Deliverable's state. It checkpoints after every step and pauses with interrupt() whenever the user must answer or approve. This follows the KAB workflow standard and the platform's langgraph-workflow-agent.
  • ADK agents reason and act. The Orchestrator and every Specialist is an ADK LlmAgent, each running its own ReAct loop, with a SkillToolset for progressive Skill loading. This follows the platform's google-adk-base-agent/app/skills_integration.py.
  • Agents sit behind one interface. Each agent runs behind a single agent-runtime interface, so LangChain Deep Agents can be added as a second implementation without touching the graph.

The dependency graph is declared as data in code. The Orchestrator picks what to do next through tools that refuse work whose dependencies aren't met. Dependencies are guaranteed by code, while ordering and parallelism are the model's choice.

Amended (2026-10-07) by ADR-0007, accepted. The Orchestrator is now a router: it decides by readings and a playbook in code, with Jev for the judgements, and runs no language model to choose an action. That replaces "the Orchestrator ... is an ADK LlmAgent" above and reverses the third option rejected below. Specialists are unaffected and still reason on language models.

Considered Options

  • ADK end to end (root LlmAgent with sub_agents/AgentTool, and ADK sessions for pauses): rejected. It departs from the KAB workflow standard, and LangGraph's checkpointed interrupt() is the proven platform path for resumable user Approvals.
  • Deep Agents end to end (create_deep_agent(skills=, subagents=)): viable, and it compiles to LangGraph. It was deferred rather than rejected: ADK SkillToolset already has working prior art on this platform, and Deep Agents stays reachable as the second implementation of the agent-runtime interface.
  • Code runs the dependency graph with no Orchestrator model: rejected. The top level wouldn't be ReAct, and the Skill's conversational flexibility (such as skipping work the user says is already approved) would need hand-coding.

Consequences

  • There are two frameworks in one process. Framework types stay inside the agent-runtime implementation and never appear in graph state.
  • ADK Skills are Experimental (Python ≥ 1.25.0), so pin the version.