[dimetron]

Summary

This PR proposes declarative graph workflows for ADK Go 2.x in kagent. A workflow is a YAML/JSON AgentSystem document (apiVersion: adk.declarative/v0.2) that describes ADK workflow.Workflow graphs and LlmAgents with no Go routing code. The controller validates it, and the Go ADK builds the equivalent ADK v2 graph at startup.

The proposal has three parts:

1. go/adk/pkg/declarative: loader, validator and builder that map the document 1:1 onto ADK Go v2 (workflow.Start, NewFunctionNode, JoinNode, AgentNode, NamedToolNode, ParallelWorker, dynamic nodes, RequestInput, routes).
2. API plumbing:
   • AgentTemplate.spec.workflowFrom (ConfigMap key);
   • a validated ADKWorkflowConfig in the ADK config proto;
   • BYO harness compilation;
   • subagent isolation (Shared | Isolated).
3. CEL, MCP and hooks, so common logic stays in YAML: classification, routing, data shaping, guardrails and remote tools.

Document model

apiVersion: adk.declarative/v0.2
kind: AgentSystem
mcp_servers:
  - { name: crm, url: "http://crm-mcp:8080/mcp" }
agents:
  - name: triage
    agent_class: Workflow
    nodes:
      - id: classify
        type: cel
        vars:
          - { name: text, expr: user.content.lowerAscii() }
        routes:                                   # ordered rules, first match wins
          - { route: BILLING, when: "vars.text.matches(r'\\b(invoice|refund)\\b')" }
          - { route: QUESTION, when: "vars.text.endsWith('?')" }
      - { id: lookup, type: tool, server: crm, tool: lookup_customer,
          retry: { max_attempts: 3, when: error.timeout } }
      - { id: reply, type: cel, output: "input.output.with(c, 'Plan: ' + c.plan)" }
      - { id: answer, type: llm, model: default, mode: single_turn,
          instruction_from: { config_map: { name: prompts, key: answer } }, tools: [crm] }
      - { id: fallback, type: cel, output: "'Please rephrase.'" }
    edges:
      - { from: START, to: classify }
      - { from: classify, to: lookup, route: BILLING }
      - { from: lookup, to: reply }
      - { from: classify, to: answer, route: QUESTION }
      - { from: classify, to: fallback, route: DEFAULT }

Node types → ADK Go 2.x

type	ADK construct	Purpose
function	workflow.NewFunctionNode	Registered Go function; may return routes
cel	function node	CEL vars, output, route/routes, state_delta
tool	NamedToolNode	Registered tool, harness tool, or remote MCP tool (server:)
llm	inline LlmAgent node	Single-turn model call with tools, prompts and hooks
agent	AgentNode	Another agent of the document
join	JoinNode	Fan-in barrier after fan-out
workflow	nested Workflow	Sub-graph with its own START (max depth 8)
parallel_worker	ParallelWorker	Map a function, tool or agent over a list (max_concurrency)
dynamic	dynamic node	Go function that schedules children under max_iters
hitl	RequestInput	Pause for a human reply

Edges support routing (route, DEFAULT) and fan-out/fan-in. timeout and retry map to NodeConfig; retry.when is a CEL predicate. As in ADK, START is the only sentinel: a node with no outgoing edges ends its branch.

CEL

• Context: expressions see input, vars, state, session, user and invocation.
• Libraries: the cel-go standard library plus the strings, regex, lists, math, sets, base64 and optionals extensions.
• Helpers: json, toJson, x.with(name, body) and default(a.b, fallback) use the same names and semantics as agentgateway CEL.
• vars and routes: vars (ordered named values) and routes (an ordered first-match rule table) replace nested cel.bind and ternary chains.
• Compile-time checks: every expression is type-checked when the document is validated, including vars.<name> references, and runs under a cost limit.

Callbacks / guardrails

before_model, after_model, before_tool and after_tool are lists of rules. Each rule is either a registered Go hook or a CEL rule:

• when + reject: short-circuit with a message.
• accept: let the call through.

Prompts, MCP and harness tools

• Prompt sources: instruction_from / global_instruction_from read from a ConfigMap. The controller inlines the text and records it in revision provenance, so a ConfigMap change rolls a new revision. Secret and env sources are rejected.
• Remote MCP: mcp_servers declares Streamable HTTP MCP servers (headers, tool filter, URL from env). An llm node lists a server in tools:; a tool node calls a single server tool.
• Harness tools: the local tool library adds read_file, write_file, list_files and bash, which work in the agent workspace.

Delivery in kagent

• AgentTemplate.spec.workflowFrom references a ConfigMap key. It is mutually exclusive with systemPrompt/systemPromptFrom, a CEL validation rule enforces this, and only a BYO Harness may use it in this first step.
• The controller validates the document with the same Go package the runtime uses. It sends the canonical JSON and its SHA-256 in ADKWorkflowConfig, which is included in provenance. Invalid documents are reported as validation errors; a missing ConfigMap is retried.
• Subagents gain isolation: Isolated. In that mode the parent calls the subagent as a tool in a new session seeded with a copy of its state, which parallel fan-out to one subagent needs.

Examples and docs

• go/adk/examples/declarative: support triage built from CEL classification, remote MCP CRM lookup, harness write_file and an LLM node with tool hooks.
• go/adk/examples/workflowpatterns: 22 patterns, each implemented twice, as Go and as YAML, and tested for identical output. The catalog in docs/architecture/workflow-patterns.md is generated from them, and a test fails if it is stale.
• docs/architecture/workflow-agents.md: reference for the document format.

Testing

• Unit tests for the loader, validator, builder, CEL, MCP (in-process loopback server), hooks, harness tools and isolation.
• Go/YAML parity tests over the 22 patterns.
• Translator tests for ConfigMap inlining, Secret rejection and provenance; envtest CRD validation tests; E2E workflow_test.go and subagent_isolation_test.go.
• make -C go lint is clean.

Not in this PR / open questions

• Managed harnesses: the kagent harness rejects workflow for now; only BYO images run documents. Should managed kagent runtimes run documents next?
• CRD: the document is embedded through a ConfigMap rather than as typed CRD fields. This keeps the public API small and avoids exposing ADK internals.
• Prompt sources: only ConfigMaps; Secret prompt sources are deferred.
• Python ADK: not covered; the schema is language-neutral, so a Python loader can follow.

Related

• Related to [FEATURE] Implement Workflow Subagents with ADK Patterns #991 (closed as not planned), which asked for declarative Sequential, Parallel and Loop workflow agents built on ADK workflow agents, and to its earlier attempt feat: add declarative workflow subagents (Sequential, Parallel, Loop) #1743 (closed without merging). This PR provides those classes (SequentialAgent, ParallelAgent, LoopAgent) together with ADK Go 2.x graph Workflow agents.