Skip to content

Fix TypeScript samples that do not compile against the ADK API - #2172

Draft
kalenkevich wants to merge 1 commit into
google:mainfrom
kalenkevich:fix/typescript-api-mismatches
Draft

Fix TypeScript samples that do not compile against the ADK API#2172
kalenkevich wants to merge 1 commit into
google:mainfrom
kalenkevich:fix/typescript-api-mismatches

Conversation

@kalenkevich

Copy link
Copy Markdown
Collaborator

What this fixes

Seven TypeScript snippets across five pages used APIs that don't exist, so
copying them produced a compile error. None of these are cosmetic — each one
fails on tsc.

Page Problem
agents/custom-agents.md, workflows/patterns.md ADK helpers imported from @google/genai
agents/custom-agents.md createEvent / createEventActions imported with import type, then called
context/index.md SearchMemoryResponse.results / .text — neither exists
plugins/index.md BasePlugin callbacks declared with positional args
tools-custom/mcp-tools.md type: "SseConnectionParams" is not a valid connection type

Details

Wrong package. @google/genai exports none of createEvent,
createEventActions or the ADK Event — only Part genuinely belongs to it.
Those imports never resolved.

import type on runtime functions. Both helpers are functions and the
samples call them, which fails with TS1361 ("cannot be used as a value because
it was imported using 'import type'").

Memory API. SearchMemoryResponse exposes memories, not results, and
each entry is a MemoryEntry whose text lives on content.parts rather than a
.text field. The TypeScript tab had mirrored the Python tab's
search_results.results literally.

Plugin callbacks. BasePlugin takes a single params object:
beforeAgentCallback({agent, callbackContext}) and
beforeModelCallback({callbackContext, llmRequest}). As written the overrides
didn't match the base signature, so they wouldn't have received their
arguments even if they had compiled.

MCP connection type. Valid values are StdioConnectionParams and
StreamableHTTPConnectionParams; the sample's own comment said it meant the
latter. Correcting type let the compiler narrow the union, which surfaced a
second problem the wrong type had been masking: headers belong on
transportOptions.requestInit.headers, because the top-level header field
is deprecated.

How these were found

Extracted every inline TypeScript block in docs/ and type-checked it against
the real @google/adk types.

One methodology note worth recording, because it made the first pass useless:
tsc skips all semantic checking when any file in the program has a syntax
error, and ~48 of the blocks are fragments that don't parse standalone. The
initial run therefore reported zero errors. Quarantining the fragments, and
planting deliberately-broken canary code to confirm the checker actually
catches things, is what surfaced these.

Also worth noting for anyone reading the audit: Event.actions,
getFunctionResponses and LlmResponse all looked broken at first but are
fine — those blocks just omit imports, so bare Event resolves to the DOM
global.

Verification

  • 102 of 149 inline TypeScript blocks now compile clean against the real API,
    up from 95. The remaining 47 are fragments that don't stand alone.
  • All 500 @google/adk imports across the docs resolve to real exports.
  • Python, Go, Java and Kotlin tabs are untouched — only the TypeScript tabs
    changed, and only where the code was wrong.

Not included

Left out deliberately, happy to fold in if you'd rather:

  1. Three arguable cases. context/index.md declares concrete agent classes
    without the abstract runLiveImpl (won't compile as written, but may be an
    intentional simplification); an authScheme placeholder that doesn't
    satisfy AuthScheme in a block labelled pseudocode; and a callback in
    sessions/memory.md returning Promise<void> where Content | undefined
    is required — that last one might be better fixed by loosening the ADK type.

  2. Snippet-package config. Separately from the docs,
    examples/typescript/snippets/agents/workflow-agents/tsconfig.json sets
    include: ["src/**/*"] but the files sit at the directory root, so tsc
    compiles nothing there; that tsconfig and callbacks/tsconfig.json also use
    an invalid ignoreDeprecations value for the TypeScript version their own
    package.json pins. Those belong with a CI job that actually compiles the
    TypeScript snippets — there isn't one today, unlike Go and Kotlin.

Seven TypeScript snippets used APIs that do not exist, so anyone copying them
got a compile error. Found by extracting every inline TypeScript block in the
docs and type-checking it against the real @google/adk types.

- Import ADK helpers from @google/adk, not @google/genai. `createEvent`,
  `createEventActions` and the ADK `Event` are not exported by @google/genai
  at all (only `Part` is), so those imports never resolved.
  (agents/custom-agents.md, workflows/patterns.md)

- Import `createEvent` / `createEventActions` as values rather than with
  `import type`. They are functions and the samples call them, which fails
  with TS1361. (agents/custom-agents.md)

- `SearchMemoryResponse` exposes `memories`, not `results`, and an entry is a
  `MemoryEntry` whose text lives on `content.parts` rather than a `.text`
  field. The old code mirrored the Python tab's `search_results.results`
  literally. (context/index.md)

- `BasePlugin` callbacks take a single params object, not positional
  arguments: `beforeAgentCallback({agent, callbackContext})` and
  `beforeModelCallback({callbackContext, llmRequest})`. As written the
  overrides did not match the base signature. (plugins/index.md)

- `MCPToolset` has no `SseConnectionParams` connection type; the valid values
  are `StdioConnectionParams` and `StreamableHTTPConnectionParams`, and the
  sample's own comment said it meant the latter. Correcting the type let the
  compiler narrow the union, which surfaced a second problem: headers belong
  on `transportOptions.requestInit.headers`, since the top-level `header`
  field is deprecated. (tools-custom/mcp-tools.md)

All five pages' blocks now type-check; 102 of 149 inline TypeScript blocks in
the docs compile clean, up from 95, with the rest being fragments that do not
stand alone. Python, Go, Java and Kotlin tabs are untouched.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant