docs(workflow): workflow samples (Part 8) (#595)

* docs(workflow): add workflow samples

Part 8/9 (final) of the feature/workflows split. Runnable examples covering the
workflow API surface:

- basics: sequence, loop, loop_self, route, multi_triggers, state, node_output,
  use_as_output, message
- parallelism & dynamic: fan_out_fan_in, parallel_worker,
  dynamic_fan_out_fan_in, dynamic_nodes, nested_workflow
- HITL & auth: request_input, request_input_advanced, request_input_rerun,
  auth_api_key, auth_oauth
- agents & tools: agent_in_workflow, node_as_tool, retry
- samples/workflows/README.md and a root `sample` script to run them

Samples import only the public `@google/adk` surface and typecheck cleanly
against source.

* docs(workflow): address PR #595 sample review feedback

- dynamic_nodes now uses a real `WorkflowConfig.dynamicEntry` (driving children
  via `ctx.runNode()`) instead of a static `edges` graph, so it actually
  demonstrates what the README row and Feature-coverage section claim — and the
  imperative loop is bounded by `MAX_ATTEMPTS` instead of `for (;;)`, so an
  off-topic input can't spin forever on live model calls.
- parallel_worker sets `maxParallelWorkers: 2`, demonstrating the bounded
  concurrency the README advertises.
- Normalize all nine sample headers that still used the raw
  `node dev/dist/esm/cli_entrypoint.js run ...` form to `npm run sample -- ...`,
  matching the README and the other samples.
- Unify how the four HITL samples parse a human reply: normalize with
  `.trim().toLowerCase()` (so "Approve"/"approve " no longer fall through) and
  share one affirmative vocabulary, instead of three different idioms.
- README: note that `loop`'s graph cycle is intentionally uncapped and can
  iterate many times; add a dynamicEntry bullet to Feature coverage.
- Fix a prompt typo ("relates the the" -> "relates to the") in parallel_worker.

* test(workflow): record/replay sample integration tests + per-test subfolders

Add integration tests that run the real workflow samples end-to-end with only
the model mocked, and reorganize tests/integration/workflows so every test lives
in its own subfolder.

- Harness (tests/integration/workflows/_harness/): a RecordReplayModel
  registered into LLMRegistry mocks the model boundary for every agent —
  including ones captured inside a dynamicEntry/ctx.runNode closure — matching
  recorded responses to requests by a stable, id-normalized fingerprint
  (concurrency/order independent). sample_harness runs the real sample rootAgent
  through an InMemoryRunner; record mode (RECORD_MODEL_RESPONSES=1) calls the
  live model and writes the fixture, replay is offline. rng provides a seeded
  PRNG for the model-free non-deterministic samples (retry, loop_self).
- 21 of 22 samples covered, one folder each: agent.ts (vendored from the sample)
  + <sample>_test.ts + model_responses.json where model-backed; offline samples
  need no fixture. auth_oauth is skipped (needs a live OAuth provider).
- Add `npm run record:samples` to re-record the model-backed fixtures.
- Move the existing Part 6 workflow integration tests into per-test subfolders
  (workflow_test_utils.ts -> _harness/; node_as_tool_test.ts -> node_as_tool_llm/
  to avoid colliding with the sample's node_as_tool/ folder), fixing relative
  imports only. No Part 6 test logic changed.

* chore: drop the sampels

* feat(workflow): let WorkflowAgent take Workflow options directly

Adds an overload so the common case drops a layer of nesting:

  new WorkflowAgent({name: 'root_agent', edges: [...]})

instead of

  new WorkflowAgent(new Workflow({name: 'root_agent', edges: [...]}))

When given a WorkflowConfig, the agent constructs the Workflow internally and
takes its name/description from that config. The existing
`new WorkflowAgent(workflow, {name, description})` form is unchanged and still
supported, so this is purely additive.

The two forms are told apart with the `isBaseNode` brand rather than
`instanceof` (per the workflow conventions): a branded node is an already-built
Workflow, anything else is config to build one from.

* refactor(workflow): use the flattened WorkflowAgent signature in tests

Adopt the new `new WorkflowAgent({name, edges})` form across the vendored agents
under tests/integration/workflows, dropping the `new Workflow(...)` wrapper and
one level of nesting:

  export const rootAgent = new WorkflowAgent({
    name: 'root_agent',
    edges: [['START', processInput, classifyInput]],
  });

- Migrates the 20 vendored agents that build a Workflow (node_as_tool is a plain
  LlmAgent and is unchanged), dropping the now-unused `Workflow` import where
  nothing else needs it. nested_workflow keeps it for its sub-workflow node.
- The samples this code was originally vendored from were removed in the
  preceding "chore: drop the sampels" commit, so only the self-contained test
  copies are updated here.

The change is purely syntactic: the workflows built are identical, so the
recorded model_responses.json fixtures still match and all 56 workflow
integration tests pass unchanged.

Author: kalenkevich

core/src/workflow/workflow_agent.ts

@@ -10,10 +10,10 @@ import {InvocationContext} from '../agents/invocation_context.js';
 import {createEvent, Event} from '../events/event.js';
 import {AsyncQueue} from '../utils/async_queue.js';
 import {experimental} from '../utils/experimental.js';
-import {toContent} from './base_node.js';
+import {isBaseNode, toContent} from './base_node.js';
 import {NodeContext} from './node_context.js';
 import {reconstructNodeStates} from './utils/rehydration_utils.js';
-import {Workflow} from './workflow.js';
+import {Workflow, WorkflowConfig} from './workflow.js';
 
 /** Options for a {@link WorkflowAgent}. */
 export interface WorkflowAgentConfig {
@@ -34,7 +34,29 @@ export interface WorkflowAgentConfig {
 export class WorkflowAgent extends BaseAgent {
   readonly workflow: Workflow;
 
-  constructor(workflow: Workflow, config: WorkflowAgentConfig = {}) {
+  /**
+   * Wraps an existing {@link Workflow}. The agent's name/description default to
+   * the workflow's; pass `config` to override them.
+   */
+  constructor(workflow: Workflow, config?: WorkflowAgentConfig);
+  /**
+   * Convenience form: pass the {@link Workflow} constructor options directly and
+   * the workflow is created internally, so you can write
+   * `new WorkflowAgent({name, edges})` instead of
+   * `new WorkflowAgent(new Workflow({name, edges}))`. The agent's name and
+   * description come from the config.
+   */
+  constructor(config: WorkflowConfig);
+  constructor(
+    workflowOrConfig: Workflow | WorkflowConfig,
+    config: WorkflowAgentConfig = {},
+  ) {
+    // A branded BaseNode is an already-built Workflow; anything else is config
+    // to build one from (avoids `instanceof`, per the workflow conventions).
+    // The overload signatures guarantee an instance here is a Workflow.
+    const workflow = isBaseNode(workflowOrConfig)
+      ? (workflowOrConfig as Workflow)
+      : new Workflow(workflowOrConfig);
     super({
       name: config.name ?? workflow.name,
       description: config.description ?? workflow.description,

core/test/workflow/workflow_agent_test.ts

@@ -9,6 +9,8 @@ import {InvocationContext} from '../../src/agents/invocation_context.js';
 import {Event} from '../../src/events/event.js';
 import {PluginManager} from '../../src/plugins/plugin_manager.js';
 import {createSession} from '../../src/sessions/session.js';
+import {isBaseNode} from '../../src/workflow/base_node.js';
+import {node} from '../../src/workflow/node.js';
 import {NodeContext} from '../../src/workflow/node_context.js';
 import {RequestInput} from '../../src/workflow/request_input.js';
 import {createRequestInputEvent} from '../../src/workflow/utils/hitl_utils.js';
@@ -79,3 +81,34 @@ describe('WorkflowAgent — plain-text resume', () => {
     expect(await resumeInputsFor(['first', 'second'], 'yes')).toEqual({});
   });
 });
+
+describe('WorkflowAgent — constructor forms', () => {
+  const step = node(() => 'done', {name: 'step'});
+
+  it('builds the Workflow from config (the convenience signature)', () => {
+    const agent = new WorkflowAgent({
+      name: 'from_config',
+      edges: [['START', step]],
+    });
+    expect(agent.name).toBe('from_config');
+    expect(isBaseNode(agent.workflow)).toBe(true);
+    expect(agent.workflow.name).toBe('from_config');
+  });
+
+  it('accepts a dynamicEntry config too', () => {
+    const agent = new WorkflowAgent({
+      name: 'dyn',
+      dynamicEntry: async () => 'ok',
+    });
+    expect(agent.workflow.name).toBe('dyn');
+  });
+
+  it('still accepts a pre-built Workflow, with optional overrides', () => {
+    const workflow = new Workflow({name: 'wf', edges: [['START', step]]});
+    expect(new WorkflowAgent(workflow).name).toBe('wf');
+    expect(new WorkflowAgent(workflow).workflow).toBe(workflow);
+    expect(new WorkflowAgent(workflow, {name: 'override'}).name).toBe(
+      'override',
+    );
+  });
+});

package.json

@@ -11,6 +11,7 @@
   },
   "scripts": {
     "build": "npm run build --workspaces",
+    "sample": "node dev/dist/esm/cli_entrypoint.js run",
     "clean": "npm run clean --workspaces",
     "clean:all": "rm package-lock.json && rm -rf ./node_modules && npm run clean:all --workspaces",
     "rebuild": "npm run clean:all && npm install && npm run build",
@@ -27,6 +28,7 @@
     "test": "vitest --project unit:core --project unit:dev --project integration --project e2e",
     "test:unit": "vitest --project unit:core --project unit:dev",
     "test:integration": "vitest --project integration",
+    "record:samples": "RECORD_MODEL_RESPONSES=1 vitest run --project integration tests/integration/workflows/*/*_test.ts",
     "test:e2e": "vitest --project e2e",
     "test:cross-language": "vitest --project cross-language",
     "test:coverage": "vitest run --project unit:core --project unit:dev --project integration --project e2e --coverage",

tests/integration/workflows/_harness/record_replay_model.ts

@@ -0,0 +1,228 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Record/replay model boundary for the workflow-sample integration tests.
+ *
+ * The samples construct `LlmAgent`s with a string model (`gemini-2.5-flash`),
+ * which every agent resolves lazily via `LLMRegistry.newLlm(...)`. We register a
+ * single {@link RecordReplayModel} for the Gemini model regexes so that EVERY
+ * agent in a sample — including ones captured inside a `dynamicEntry`/`ctx.runNode`
+ * closure that static traversal can't reach — resolves to it.
+ *
+ * - Replay (default): each model call is matched to a recorded response by a
+ *   stable fingerprint of its request. Concurrency- and order-independent, so
+ *   parallel samples need no special casing. A miss throws with a re-record hint.
+ * - Record (`RECORD_MODEL_RESPONSES=1`): the call is delegated to a real Gemini
+ *   and the raw response is captured keyed by the same fingerprint.
+ */
+
+import type {BaseLlmConnection, LlmRequest, LlmResponse} from '@google/adk';
+import {BaseLlm, Gemini, LLMRegistry} from '@google/adk';
+import type {Candidate} from '@google/genai';
+import {createHash} from 'node:crypto';
+import type {RawGenerateContentResponse} from '../../test_case_utils.js';
+
+/** A single recorded model call: its request fingerprint and raw response. */
+export interface RecordedCall {
+  /** Stable fingerprint of the request (see {@link fingerprint}). */
+  key: string;
+  /** A readable snippet of the request, for debugging the fixture. */
+  request: {contents: unknown; systemInstruction?: unknown};
+  /** The raw response to replay. */
+  response: RawGenerateContentResponse;
+}
+
+type Mode = 'record' | 'replay';
+
+interface HarnessState {
+  mode: Mode;
+  recorded: RecordedCall[];
+  replay: Map<
+    string,
+    {responses: RawGenerateContentResponse[]; cursor: number}
+  >;
+  /** Backend used in record mode (default: a real Gemini). Overridable in tests. */
+  liveBackend: (model: string) => BaseLlm;
+}
+
+let state: HarnessState | undefined;
+
+/** Recursively sorts object keys so JSON serialization is stable. */
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+      out[k] = sortKeys((value as Record<string, unknown>)[k]);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Strips volatile fields (randomly-generated `id`s on function calls/responses)
+ * so a request fingerprints identically across the record run and later replays.
+ */
+function normalizeContents(contents: unknown): unknown {
+  const clone = structuredClone(contents) as unknown;
+  const scrub = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(scrub);
+      return;
+    }
+    if (node && typeof node === 'object') {
+      const obj = node as Record<string, unknown>;
+      if ('functionCall' in obj && obj['functionCall']) {
+        delete (obj['functionCall'] as Record<string, unknown>)['id'];
+      }
+      if ('functionResponse' in obj && obj['functionResponse']) {
+        delete (obj['functionResponse'] as Record<string, unknown>)['id'];
+      }
+      for (const v of Object.values(obj)) scrub(v);
+    }
+  };
+  scrub(clone);
+  return clone;
+}
+
+/** Stable fingerprint of a model request (contents + config, id-normalized). */
+export function fingerprint(req: LlmRequest): string {
+  const material = JSON.stringify(
+    sortKeys({
+      contents: normalizeContents(req.contents),
+      config: req.config ?? {},
+    }),
+  );
+  return createHash('sha256').update(material).digest('hex').slice(0, 16);
+}
+
+/** Reconstructs the raw response shape the fixture stores from an LlmResponse. */
+function toRaw(resp: LlmResponse): RawGenerateContentResponse {
+  const candidate: Candidate = {
+    content: resp.content,
+    finishReason: resp.finishReason,
+    groundingMetadata: resp.groundingMetadata,
+    citationMetadata: resp.citationMetadata,
+  };
+  return {
+    candidates: resp.content ? [candidate] : [],
+    usageMetadata: resp.usageMetadata,
+  };
+}
+
+/** Inflates a recorded raw response back into an LlmResponse for replay. */
+function toLlmResponse(raw: RawGenerateContentResponse): LlmResponse {
+  const candidate = raw.candidates?.[0];
+  return {
+    content: candidate?.content,
+    finishReason: candidate?.finishReason,
+    groundingMetadata: candidate?.groundingMetadata,
+    citationMetadata: candidate?.citationMetadata,
+    usageMetadata: raw.usageMetadata,
+  };
+}
+
+/**
+ * The model registered for the Gemini regexes during a sample test. It reuses
+ * `Gemini.supportedModels` (the same RegExp instances) so registering it
+ * overwrites Gemini's registry entries rather than adding lower-priority ones.
+ */
+class RecordReplayModel extends BaseLlm {
+  static override readonly supportedModels = Gemini.supportedModels;
+
+  override async *generateContentAsync(
+    llmRequest: LlmRequest,
+    stream = false,
+    abortSignal?: AbortSignal,
+  ): AsyncGenerator<LlmResponse, void> {
+    if (!state) {
+      throw new Error(
+        'RecordReplayModel used without installRecordReplay(); did the harness set it up?',
+      );
+    }
+    const key = fingerprint(llmRequest);
+
+    if (state.mode === 'replay') {
+      const entry = state.replay.get(key);
+      if (!entry) {
+        throw new Error(
+          `No recorded model response for request fingerprint ${key}. ` +
+            'Re-record with: npm run record:samples',
+        );
+      }
+      // Deterministic: identical requests reuse the last recorded response.
+      const raw =
+        entry.responses[Math.min(entry.cursor, entry.responses.length - 1)];
+      entry.cursor++;
+      yield toLlmResponse(raw);
+      return;
+    }
+
+    // Record: delegate to a real backend and capture the raw response.
+    const backend = state.liveBackend(this.model);
+    for await (const resp of backend.generateContentAsync(
+      llmRequest,
+      stream,
+      abortSignal,
+    )) {
+      state.recorded.push({
+        key,
+        request: {
+          contents: normalizeContents(llmRequest.contents),
+          systemInstruction: llmRequest.config?.systemInstruction,
+        },
+        response: toRaw(resp),
+      });
+      yield resp;
+    }
+  }
+
+  override connect(_llmRequest: LlmRequest): Promise<BaseLlmConnection> {
+    throw new Error('RecordReplayModel does not support live connections.');
+  }
+}
+
+/**
+ * Installs the record/replay model into the LLM registry and sets the mode.
+ * Call once per test run (before the runner executes).
+ */
+export function installRecordReplay(opts: {
+  mode: Mode;
+  recordedCalls?: RecordedCall[];
+  liveBackend?: (model: string) => BaseLlm;
+}): void {
+  const replay = new Map<
+    string,
+    {responses: RawGenerateContentResponse[]; cursor: number}
+  >();
+  for (const call of opts.recordedCalls ?? []) {
+    const entry = replay.get(call.key) ?? {responses: [], cursor: 0};
+    entry.responses.push(call.response);
+    replay.set(call.key, entry);
+  }
+  state = {
+    mode: opts.mode,
+    recorded: [],
+    replay,
+    liveBackend: opts.liveBackend ?? ((model: string) => new Gemini({model})),
+  };
+  LLMRegistry.register(RecordReplayModel);
+}
+
+/** Restores the real Gemini registration and clears harness state. */
+export function restoreRecordReplay(): void {
+  LLMRegistry.register(Gemini);
+  state = undefined;
+}
+
+/** Returns the calls captured during a record run. */
+export function drainRecordedCalls(): RecordedCall[] {
+  return state?.recorded ?? [];
+}

tests/integration/workflows/_harness/rng.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Deterministic PRNG (mulberry32) for tests that stub `Math.random`. Samples
+ * like `retry` and `loop_self` are model-free but use `Math.random`; seeding it
+ * makes them reproducible. A seeded generator (rather than a constant) keeps the
+ * engine's own random event-id generation varied, so ids don't collide.
+ */
+export function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}