Fix TypeScript samples that do not compile against the ADK API - #2172
Draft
kalenkevich wants to merge 1 commit into
Draft
Fix TypeScript samples that do not compile against the ADK API#2172kalenkevich wants to merge 1 commit into
kalenkevich wants to merge 1 commit into
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.agents/custom-agents.md,workflows/patterns.md@google/genaiagents/custom-agents.mdcreateEvent/createEventActionsimported withimport type, then calledcontext/index.mdSearchMemoryResponse.results/.text— neither existsplugins/index.mdBasePlugincallbacks declared with positional argstools-custom/mcp-tools.mdtype: "SseConnectionParams"is not a valid connection typeDetails
Wrong package.
@google/genaiexports none ofcreateEvent,createEventActionsor the ADKEvent— onlyPartgenuinely belongs to it.Those imports never resolved.
import typeon runtime functions. Both helpers are functions and thesamples call them, which fails with TS1361 ("cannot be used as a value because
it was imported using 'import type'").
Memory API.
SearchMemoryResponseexposesmemories, notresults, andeach entry is a
MemoryEntrywhose text lives oncontent.partsrather than a.textfield. The TypeScript tab had mirrored the Python tab'ssearch_results.resultsliterally.Plugin callbacks.
BasePlugintakes a single params object:beforeAgentCallback({agent, callbackContext})andbeforeModelCallback({callbackContext, llmRequest}). As written the overridesdidn't match the base signature, so they wouldn't have received their
arguments even if they had compiled.
MCP connection type. Valid values are
StdioConnectionParamsandStreamableHTTPConnectionParams; the sample's own comment said it meant thelatter. Correcting
typelet the compiler narrow the union, which surfaced asecond problem the wrong type had been masking: headers belong on
transportOptions.requestInit.headers, because the top-levelheaderfieldis deprecated.
How these were found
Extracted every inline TypeScript block in
docs/and type-checked it againstthe real
@google/adktypes.One methodology note worth recording, because it made the first pass useless:
tscskips all semantic checking when any file in the program has a syntaxerror, 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,getFunctionResponsesandLlmResponseall looked broken at first but arefine — those blocks just omit imports, so bare
Eventresolves to the DOMglobal.
Verification
up from 95. The remaining 47 are fragments that don't stand alone.
@google/adkimports across the docs resolve to real exports.changed, and only where the code was wrong.
Not included
Left out deliberately, happy to fold in if you'd rather:
Three arguable cases.
context/index.mddeclares concrete agent classeswithout the abstract
runLiveImpl(won't compile as written, but may be anintentional simplification); an
authSchemeplaceholder that doesn'tsatisfy
AuthSchemein a block labelled pseudocode; and a callback insessions/memory.mdreturningPromise<void>whereContent | undefinedis required — that last one might be better fixed by loosening the ADK type.
Snippet-package config. Separately from the docs,
examples/typescript/snippets/agents/workflow-agents/tsconfig.jsonsetsinclude: ["src/**/*"]but the files sit at the directory root, sotsccompiles nothing there; that tsconfig and
callbacks/tsconfig.jsonalso usean invalid
ignoreDeprecationsvalue for the TypeScript version their ownpackage.jsonpins. Those belong with a CI job that actually compiles theTypeScript snippets — there isn't one today, unlike Go and Kotlin.