Feat: Implement Gemini Interaction API in adk-js by AmaadMartin · Pull Request #364 · google/adk-js

AmaadMartin · 2026-05-21T19:48:07Z

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

Link to an existing issue (if applicable):
N/A

Closes: #issue_number
Related: #issue_number
2. Or, if no issue exists, describe the change:
This PR implements the next-generation stateful Gemini Interaction API integration in adk-js, mirroring the design and functionality already present in adk-python. This enables stateful, multi-turn conversations by tracking interaction history server-side using interactionId, reducing payload sizes across progressive turns.

If applicable, please follow the issue templates to provide as much detail as possible.

Problem:
The current adk-js core only supports stateless execution via the standard generateContent API, which requires sending the entire conversational history back and forth on every turn. This increases payload sizes, causes overhead, and prevents leveraging server-side interaction history tracking.

Solution:

Interface Updates:
- Added optional previousInteractionId?: string to LlmRequest in core/src/models/llm_request.ts.
- Added optional interactionId?: string to LlmResponse in core/src/models/llm_response.ts.
Stateful Request Processor:
- Created InteractionsRequestProcessor under core/src/agents/processors/interactions_request_processor.ts. It automatically traverses the session events history in reverse to find the latest valid interactionId for the current branch and sub-agent name, injecting it as previousInteractionId into the outgoing request.
- Registered INTERACTIONS_REQUEST_PROCESSOR in LlmAgent request processors, immediately following the CONTENT_REQUEST_PROCESSOR.
Interaction Utility & Payload Transformation:
- Created core/src/models/interactions_utils.ts containing:
  - getLatestUserContents to trim the outgoing conversation history, sending only the latest continuous user turn when previousInteractionId is present (with special handling to retain the preceding model turn's function call if the user turn contains a function response).
  - Request/response converters mapping ADK types (text, function calls, tool results, media data, code execution) to @google/genai Interactions REST schemas (and vice-versa).
  - Core streaming/non-streaming runner generateContentViaInteractions wrapping @google/genai interactions resource calls.
Model Integration:
- Updated Gemini class (core/src/models/google_llm.ts) to accept useInteractionsApi?: boolean parameter, toggling the flow to delegate to generateContentViaInteractions when enabled.

Testing Plan
Please describe the tests that you ran to verify your changes. This is required for all PRs that are not small documentation or typo fixes.

Unit Tests:

I have added or updated unit tests for my change.
All unit tests pass locally.

We implemented extensive unit tests targeting the stateful request processor and the payload converters:

core/test/agents/processors/interactions_request_processor_test.ts (6 tests)
core/test/models/interactions_utils_test.ts (89 tests)

Summary of passed npm test results:

 RUN  v3.2.4 /usr/local/google/home/amaadmartin/Workspace/Agentspaces/feat-interactions-api-2/adk-js

 Test Files  2 passed (2)
      Tests  95 passed (95)
   Start at  13:17:31
    Duration  10.68s

We achieved 100% Statement, Branch, Function, and Line coverage for both new source files in adk-js/core:

core/src/agents/processors/interactions_request_processor.ts: 100% Coverage
core/src/models/interactions_utils.ts: 100% Coverage

Manual End-to-End (E2E) Tests:
We created a verification script verify_interactions.ts in the root of the workspace. It tests a two-turn conversation:

Turn 1: "My favorite color is deep blue. Remember this." (verifies the model responds and returns a valid interactionId).
Turn 2: "What is my favorite color?" with previousInteractionId set (verifies history is trimmed and the model correctly recalls "blue" from the server-side state).

To execute manual verification:

GEMINI_API_KEY=your_live_api_key npx tsx verify_interactions.ts

Checklist

I have read the CONTRIBUTING.md document.
I have performed a self-review of my own code.
I have commented my code, particularly in hard-to-understand areas.
I have added tests that prove my fix is effective or that my feature works.
New and existing unit tests pass locally with my changes.
I have manually tested my changes end-to-end.
Any dependent changes have been merged and published in downstream modules.

Additional context
TAG=agy
CONV=8a91ed6a-f4db-4160-83d9-68d5e80e066c

…mResponse

…ns API

…on scratch file

…olve CI E401 error

…DK 2.0 type inheritance checks in CI

kalenkevich · 2026-06-01T17:56:34Z

+  text?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  functionCall?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  functionResponse?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inlineData?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  fileData?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  thoughtSignature?: any;
+  thought?: boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  codeExecutionResult?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  executableCode?: any;


please remove, use Part type from @google/genai

I've audited the SDK type definitions and confirmed that the native Part type from @google/genai already natively contains all these fields. I have removed the ExtendedPart interface entirely and refactored the utility functions to parse standard Part objects directly.

kalenkevich · 2026-06-01T17:57:36Z

+interface ExtendedTool {
+  functionDeclarations?: Array<{
+    name: string;
+    description?: string;
+    parameters?: {
+      properties?: Record<string, unknown>;
+      required?: string[];
+    };
+    parametersJsonSchema?: unknown;
+  }>;
+  googleSearch?: unknown;
+  codeExecution?: unknown;
+  urlContext?: unknown;
+}
+
+interface InteractionTextContent {
+  type: 'text';
+  text: string;
+}
+
+interface InteractionFunctionCall {
+  type: 'function_call';
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  thought_signature?: string;
+}
+
+interface InteractionFunctionResult {
+  type: 'function_result';
+  name: string;
+  call_id: string;
+  result: unknown;
+}
+
+interface InteractionMediaContent {
+  type: 'image' | 'audio' | 'video' | 'document';
+  data?: string;
+  uri?: string;
+  mime_type: string;
+}
+
+interface InteractionThought {
+  type: 'thought';
+  signature?: string;
+}
+
+interface InteractionCodeExecutionCall {
+  type: 'code_execution_call';
+  id: string;
+  arguments: {
+    code: string;
+    language: string;
+  };
+}
+
+interface InteractionCodeExecutionResult {
+  type: 'code_execution_result';
+  call_id: string;
+  result: string;
+  is_error: boolean;
+}
+
+type InteractionContent =
+  | InteractionTextContent
+  | InteractionFunctionCall
+  | InteractionFunctionResult
+  | InteractionMediaContent
+  | InteractionThought
+  | InteractionCodeExecutionCall
+  | InteractionCodeExecutionResult;
+
+interface InteractionTurn {
+  role: string;
+  content: InteractionContent[];
+}
+
+interface InteractionTool {
+  type: 'function' | 'google_search' | 'code_execution' | 'url_context';
+  name?: string;
+  description?: string;
+  parameters?: unknown;
+}
+
+interface InteractionResponse {
+  id: string;
+  status: 'completed' | 'requires_action' | 'failed' | string;
+  error?: {
+    code: string;
+    message: string;
+  };
+  outputs?: Record<string, unknown>[];
+  usage?: {
+    total_input_tokens?: number;
+    total_output_tokens?: number;
+  };
+}
+
+interface InteractionSSEEvent {
+  event_type?: string;
+  eventType?: string;
+  delta?: {
+    type: string;
+    text?: string;
+    name?: string;
+    id?: string;
+    arguments?: Record<string, unknown>;
+    thought_signature?: string;
+    data?: string;
+    uri?: string;
+    mime_type: string;
+  };
+  status?: string;
+  error?: {
+    code: string;
+    message: string;
+  };
+  code?: string;
+  message?: string;
+  interaction_id?: string;
+  interactionId?: string;
+  interaction?: {
+    id: string;
+  };
+  id?: string;
+}
+
+interface GoogleGenAIWithInteractions {
+  interactions: {
+    create(params: {
+      model?: string;
+      input: InteractionTurn[];
+      stream: boolean;
+      systemInstruction?: string;
+      tools?: InteractionTool[];
+      generationConfig?: Record<string, unknown>;
+      previousInteractionId?: string;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }): Promise<any>; // We keep 'any' here as the SDK return type is complex (stream vs non-stream)
+  };
+}


Can we get those types from @google/genai?

I have replaced all custom interaction types (InteractionContent, InteractionTurn, InteractionTool, InteractionResponse, InteractionSSEEvent, etc.) with native counterparts provided by @google/genai (like Interactions.Content, Interactions.Turn, Interactions.Tool, and Interactions.Interaction).

To handle runtime/SDK discrepancies typesafely without casting to any:

Defined local ExtendedInteraction and ExtendedInteractionStatusUpdate interfaces extending the SDK types to cleanly declare the runtime error fields.

Adjusted the stream event parser to fall back to delta.signature || delta.thought_signature and correctly map nested error objects for standard ErrorEvents.

Removed the obsolete GoogleGenAIWithInteractions client wrapper since GoogleGenAI has a native interactions getter.

kalenkevich · 2026-06-01T17:57:53Z

+  if (mimeType.startsWith('image/')) {
+    return 'image';
+  } else if (mimeType.startsWith('audio/')) {
+    return 'audio';
+  } else if (mimeType.startsWith('video/')) {
+    return 'video';
+  } else {
+    return 'document';
+  }


please use switch case instead

Refactored getInteractionMediaType to split mimeType by / and use a clean switch statement on the primary media type prefix (e.g., image, audio).

…olve PR comments

… timeouts

…ions_utils

Amaad Martin added 11 commits May 20, 2026 13:11

Feat: Add previousInteractionId to LlmRequest and interactionId to Ll…

78eaec8

…mResponse

Feat: Implement and register InteractionsRequestProcessor

b7ff160

Feat: Implement interactions_utils for mapping and running Interactio…

18494c0

…ns API

Feat: Integrate Interactions API into Gemini model class

81285df

Test: Add unit tests for Interactions API and verify script

ab2cf0b

Test: Add unit test edge cases for 100% statement and branch coverage

3c044e8

Fix: Remove MIME type checking code duplication and delete verificati…

8aa7b81

…on scratch file

Chore: Upgrade @google/genai SDK to version 2.0.0

a7fe707

Fix: Point @google/genai package resolution to public registry to res…

c219001

…olve CI E401 error

Fix: Make structural interfaces independent to resolve strict GenAI S…

205a906

…DK 2.0 type inheritance checks in CI

kalenkevich reviewed Jun 1, 2026

View reviewed changes

Refactor interactions API integration to use native SDK types and res…

c4561d4

…olve PR comments

AmaadMartin force-pushed the feat/interactions-api-2 branch from fdad857 to c4561d4 Compare June 1, 2026 19:50

AmaadMartin and others added 7 commits June 1, 2026 12:51

Merge branch 'main' into feat/interactions-api-2

7a2cb68

refactor(test): optimize interactions utils and fix agent loader test…

f9d74a6

… timeouts

refactor(types): remove explicit any and eslint-disable from interact…

50e0152

…ions_utils

Merge branch 'main' into feat/interactions-api-2

b96ee03

Merge branch 'main' into feat/interactions-api-2

4ed4f03

Merge branch 'main' into feat/interactions-api-2

2d303eb

Merge branch 'main' into feat/interactions-api-2

1ff040d

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feat: Implement Gemini Interaction API in adk-js#364

Feat: Implement Gemini Interaction API in adk-js#364
AmaadMartin wants to merge 19 commits into
google:mainfrom
AmaadMartin:feat/interactions-api-2

AmaadMartin commented May 21, 2026

Uh oh!

kalenkevich Jun 1, 2026

Uh oh!

AmaadMartin Jun 1, 2026

Uh oh!

kalenkevich Jun 1, 2026

Uh oh!

AmaadMartin Jun 1, 2026

Uh oh!

kalenkevich Jun 1, 2026

Uh oh!

AmaadMartin Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

AmaadMartin commented May 21, 2026

Uh oh!

kalenkevich Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

AmaadMartin Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

kalenkevich Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

AmaadMartin Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

kalenkevich Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

AmaadMartin Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants