feat(devtools): add Reasoning Engine server compatibility routes and headers parser (Agent Engine Deployment Artifact registry fix part 1) by AmaadMartin · Pull Request #440 · google/adk-js

AmaadMartin · 2026-06-16T20:19:48Z

Please ensure you have read the contribution guide https://google.github.io/adk-docs/contributing-guide/ before creating a pull request.

Link to Issue or Description of Change

Link to an existing issue (if applicable):

• Closes: #none
• Related: #none

Or, if no issue exists, describe the change:

Problem:
Vertex AI's Reasoning Engine execution gateway and liveness checks impose two key constraints:

Containers must pass liveness probes at / and /health without redirects (Vertex AI kills containers that return 3xx codes, which broke ADK because it redirected / to /dev-ui).
Vertex AI forwards query payloads with duplicate content-type headers (Content-Type: application/json,application/json), which causes Express's standard body-parser to skip parsing and results in empty request bodies {}.

Solution:
Implemented native routing in adk_api_server.ts for /health and / endpoints to return 200 OK when the Debug UI is disabled. Added a custom raw-body fallback stream listener on the POST /api/reasoning_engine query endpoint to parse incoming payloads manually if standard body-parser was skipped.

Testing Plan

Unit Tests:

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

Summary of passed test results:

✓ |unit:dev| dev/test/server/adk_api_server_test.ts (45 tests) 3797ms
✓ AdkWebServer > Reasoning Engine > should return 200 OK on health endpoints when debug UI is disabled 99ms
✓ AdkWebServer > Reasoning Engine > should query the agent using reasoning_engine route with valid JSON 42ms
✓ AdkWebServer > Reasoning Engine > should auto-create session if not exists on reasoning_engine query 56ms
✓ AdkWebServer > Reasoning Engine > should support raw body query and parse headers workaround 83ms
✓ AdkWebServer > Reasoning Engine > should return 400 if appName is missing 36ms
✓ AdkWebServer > Reasoning Engine > should return 500 if execution fails 34ms

Files tested:

• dev/test/server/adk_api_server_test.ts

Manual End-to-End (E2E) Tests:

Manually deployed and verified querying the weather tool agent on Vertex AI Reasoning Engines with unmocked traffic.

Checklist

I have read the CONTRIBUTING.md https://github.com/google/adk-js/blob/main/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.

Additional context

None.

…headers parser

…oning Engine routes

kalenkevich · 2026-06-16T21:05:36Z

+          let session = await this.sessionService.getSession({
+            appName,
+            userId,
+            sessionId,
+          });
+          if (!session) {
+            this.logger.info(
+              `Session ${sessionId} not found. Creating it automatically.`,
+            );
+            session = await this.sessionService.createSession({
+              appName,
+              userId,
+              sessionId,
+              state: {},
+            });
+          }
+          await using agentFile = await this.agentLoader.getAgentFile(appName);
+          const agent = await agentFile.load();
+          const runner = await this.getRunner(agent, appName);
+          const events: Event[] = [];
+          const abortController = new AbortController();


we have getOrCreateSession

Good point. Refactored to use the existing getOrCreateSession helper.

kalenkevich · 2026-06-16T21:08:05Z

+          await using agentFile = await this.agentLoader.getAgentFile(appName);
+          const agent = await agentFile.load();
+          const runner = await this.getRunner(agent, appName);
+          const events: Event[] = [];
+          const abortController = new AbortController();
+          req.on('close', () => {
+            abortController.abort();
+          });
+          for await (const e of runner.runAsync({
+            userId,
+            sessionId,
+            newMessage,
+            stateDelta,
+            abortSignal: abortController.signal,
+          })) {
+            events.push(e);
+          }
+          res.json({output: events});
+        } catch (e: unknown) {
+          const error = `Failed to run agent via Reasoning Engine API: ${e}`;
+          res.status(500).json({error});
+          this.logger.error(error);


very similar to run_sse can we move the common logic to the same place?

Refactored the core execution block (agent load, runner fetch, run loop, and event streaming) into a shared executeAgentRun helper. This helper is now reused in /run, /run_sse, and the Reasoning Engine query endpoints to keep them clean and consistent.

…xecution helper in api server

kalenkevich · 2026-06-18T21:45:36Z

    return this.runnerCache[appName];
  }
+
+  private async executeAgentRun(options: {


make it as generator and then no need to introduce a onEvent callback.

Implemented! Refactored executeAgentRun to be an async generator and delegate events using yield*. This cleaned up the callsites as well.

…ng callback

kalenkevich · 2026-06-22T18:33:45Z

+    newMessage: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+    stateDelta?: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+    runConfig?: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+    abortSignal: AbortSignal;


do not use any type, please use real types instead

Done. Resolved by using TypeScript indexed access types to extract the exact types from the Runner['runAsync'] parameter object (e.g., Parameters<Runner['runAsync']>[0]['newMessage'] for the newMessage field). This keeps the helper signature 100% type-safe and aligned with the runner's API without introducing duplicate type declarations or direct imports of internal SDK types.

Update: Replaced the indexed parameter types with the cleaner, direct types: Content (imported from @google/genai), Record<string, unknown>, and RunConfig (imported from @google/adk). This makes the helper signature much more readable.

… parameter types

…dexed access types in helper

Amaad Martin added 2 commits June 16, 2026 12:11

feat(devtools): add Reasoning Engine server compatibility routes and …

bfa72cd

…headers parser

fix(devtools): resolve stream consumption hang and add tests for Reas…

14d8c98

…oning Engine routes

AmaadMartin mentioned this pull request Jun 16, 2026

feat(cli): deploy agent engine to Artifact Registry instead of GCR (Agent Engine Deployment Artifact registry fix part 2) #441

Merged

8 tasks

github-actions Bot assigned Varun-S10 Jun 16, 2026

AmaadMartin changed the title ~~feat(devtools): add Reasoning Engine server compatibility routes and headers parser~~ feat(devtools): add Reasoning Engine server compatibility routes and headers parser (Agent Engine Deployment Artifact registry fix part 1) Jun 16, 2026

kalenkevich reviewed Jun 16, 2026

View reviewed changes

refactor(devtools): use getOrCreateSession and extract common query e…

a018a77

…xecution helper in api server

AmaadMartin mentioned this pull request Jun 17, 2026

fix(cli): use Artifact Registry for Agent Engine deployment #435

Closed

9 tasks

kalenkevich reviewed Jun 18, 2026

View reviewed changes

refactor(devtools): change executeAgentRun to async generator, removi…

3aaff9b

…ng callback

kalenkevich reviewed Jun 22, 2026

View reviewed changes

Amaad Martin added 2 commits June 22, 2026 11:54

refactor(devtools): replace any types with precise Runner['runAsync']…

da58410

… parameter types

refactor(devtools): use Content and RunConfig types instead of any/in…

e164a36

…dexed access types in helper

kalenkevich approved these changes Jun 22, 2026

View reviewed changes

AmaadMartin merged commit fd94e49 into main Jun 22, 2026
14 of 15 checks passed

AmaadMartin deleted the feat/reasoning-engine-server-support branch June 22, 2026 19:19

kalenkevich mentioned this pull request Jun 22, 2026

Release: v1.3.0 #407

Merged

kalenkevich linked an issue Jun 22, 2026 that may be closed by this pull request

[ADK CLI] Failed deployment to Agent Engine due to deprecated gcr.io registry & unhandled API errors #429

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(devtools): add Reasoning Engine server compatibility routes and headers parser (Agent Engine Deployment Artifact registry fix part 1)#440

feat(devtools): add Reasoning Engine server compatibility routes and headers parser (Agent Engine Deployment Artifact registry fix part 1)#440
AmaadMartin merged 6 commits into
mainfrom
feat/reasoning-engine-server-support

AmaadMartin commented Jun 16, 2026 •

edited

Loading

Uh oh!

kalenkevich Jun 16, 2026

Uh oh!

AmaadMartin Jun 17, 2026

Uh oh!

kalenkevich Jun 16, 2026

Uh oh!

AmaadMartin Jun 17, 2026

Uh oh!

kalenkevich Jun 18, 2026

Uh oh!

AmaadMartin Jun 22, 2026

Uh oh!

kalenkevich Jun 22, 2026

Uh oh!

AmaadMartin Jun 22, 2026

Uh oh!

AmaadMartin Jun 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

AmaadMartin commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Link to Issue or Description of Change

Testing Plan

Checklist

Additional context

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AmaadMartin commented Jun 16, 2026 •

edited

Loading