feat(dev): agent-proxy routes for the Agent Inspector by tejaskash · Pull Request #2085 · aws/agentcore-cli

tejaskash · 2026-08-24T17:31:27Z

What

Adds the Agent Inspector routes that talk to a running agent or read the project spec. This layer is still a pure request-to-response handler and is not reachable from the CLI yet. The project dev wiring lands in #2086.

Routes

POST /invocations — protocol-aware proxy. HTTP, A2A, and AGUI agents are each normalized into the SPA's data: <json> SSE contract. MCP returns a clear error pointing at /api/mcp rather than being proxied as HTTP.
POST /api/mcp — forwards a JSON-RPC body to the agent's /mcp endpoint, buffering the reply under a 10MB cap.
GET /api/a2a/agent-card — fetches the running agent's A2A card.
GET /api/resources — flattens project.spec into the resource graph the SPA renders.

Tests

Every route is unit tested behind fake deps: invocation routing and SSE normalization (including A2A dedup and the non-streaming fallback), the MCP forward and its size cap, the agent-card paths, the resource graph, and httpServer's streaming and abort handling.

bun test, typecheck, lint:check, format:check all green.

codecov-commenter · 2026-08-25T17:49:02Z

Codecov Report

❌ Patch coverage is 99.09707% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.39%. Comparing base (097e1f0) to head (279c0da).
⚠️ Report is 2 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/core/dev/inspector/proxies.ts	94.28%	4 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2085      +/-   ##
============================================
+ Coverage     97.38%   97.39%   +0.01%     
============================================
  Files           440      449       +9     
  Lines         26626    27474     +848     
============================================
+ Hits          25929    26759     +830     
- Misses          697      715      +18

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Add the Inspector routes that talk to a running agent or read the project spec, extending the C1 route table: - POST /invocations proxies HTTP, A2A, and AGUI agents, normalizing each into the SPA's data:<json> SSE contract. MCP agents get a clear error directing them to /api/mcp rather than being mis-proxied as HTTP. - POST /api/mcp forwards a JSON-RPC body to the agent's /mcp endpoint and buffers the reply under a 10MB cap. - GET /api/a2a/agent-card fetches the running agent's A2A card. - GET /api/resources flattens the project spec into the resource graph. Every upstream fetch carries the client's abort signal, and io/httpServer streams async-iterable bodies with backpressure so a disconnect tears the upstream request down on Node. A single session id threads through the request header, agent body, and echoed x-session-id. SSE parsing follows the framing rules (optional leading space, multi-line data fields, blank-line event boundary) instead of a hardcoded slice.

- collapse invokeHttpAgent/invokeAguiAgent into a shared forwardInvocation - single-return parseAgentEvent normalizing empty payloads to null - hoist the SSE TextEncoder to module scope - readCapped iterates over the shared iterateBody helper - drop the a2aId counter; A2A message ids use randomUUID - add the AGUI missing-prompt test

Delete JSDoc and inline notes that narrate what the code already shows. Keep only one-line notes for non-obvious reasoning (security guards, cross-runtime disconnect behavior, wire-contract field names, SSE framing).

…atch - Inline the single-caller invokeHttpAgent wrapper into handleInvocations. - Make invokeAguiAgent async so its guard returns apiError directly. - Return kind from extractSseEventText instead of re-deriving it in a separate isStatusUpdateEvent pass. - Collapse the A2A part/artifact accumulator loops into filter/map/join.

- Populate the resources fixture with one of every resource type so each wire-shaping map callback is exercised (was 55% covered). - Add invocation unhappy paths: upstream 502s, parseAgentEvent null frames, A2A artifact/task extraction, non-streaming and non-JSON fallbacks. - Cover httpServer backpressure drain and the post-headers stream error.

Hweinstock

LGTM! some small suggestions/questions but no blockers.

Hweinstock · 2026-08-26T19:49:34Z

  return json(200, status);
 }

-/** POST /api/start — start an agent on demand; concurrent starts share one attempt. */


q: were these removed on purpose?

Yes, on purpose. Those route JSDocs just restated the method/path already visible in the handler, so the comment-cleanup pass dropped them per the no-restating-the-code guideline. The security and wire-contract comments stayed.

Hweinstock · 2026-08-26T20:14:55Z

+      body,
+      signal,
+    });
+  } catch (error) {


would there be a benefit to wire the logger here?

There's no logger in this layer today (the dev handler surfaces status via renderStatus and lets errors propagate). The upstream failure already reaches the user as the 502 body in the Inspector, so I left it. Happy to add structured logging if we introduce a logger dep for the dev command more broadly.

Hweinstock · 2026-08-26T20:17:05Z

+// Handles bedrock {text}, {error}, ConverseStream contentBlockDelta, bare JSON string, and non-JSON tokens.
+export function parseAgentEvent(data: string): string | { error: string } | null {
+  try {
+    const parsed: unknown = JSON.parse(data);


would it simplify this code to use a zod schema that we parse with?

I looked at it — zod does not buy much here. parseAgentEvent takes loosely-typed passthrough tokens from arbitrary agent runtimes, handles several shapes ({text}, {error}, ConverseStream delta, bare string) AND a non-JSON fallback that returns the raw token. A zod union would still need the try/catch + raw fallback + empty-to-null glue, so the imperative form stays clearer. Left as is.

Hweinstock · 2026-08-26T20:18:36Z

+}
+
+// When streamedFromStatus is set, artifact-update text is skipped because status-update already streamed it.
+function extractSseEventText(


should this function signature / name mention that its A2A specific?

Good call — renamed to extractA2aEventText in #2086 (0791591). It only handles A2A artifact/status/task kinds, so the generic SSE name was misleading.

Hweinstock · 2026-08-26T20:22:07Z

+    expect(await response.text()).toBe(`data: ${JSON.stringify({ error: "boom" })}\n\n`);
+  });
+
+  test("passes a non-SSE response body through untouched", async () => {


i like how readable these tests are.

Hweinstock · 2026-08-26T20:36:28Z

+): Promise<void> {
+  for await (const chunk of body) {
+    if (signal.aborted) break;
+    if (!response.write(chunk)) await drain(response, signal);


nice and simple!

Rename extractSseEventText to extractA2aEventText; it only handles A2A artifact/status/task event kinds, so the generic SSE name misled. Addresses review feedback on #2085.

agentcore-devx-automation · 2026-08-27T15:15:36Z

Claude Security Review: no high-confidence findings. (run)

Rename extractSseEventText to extractA2aEventText; it only handles A2A artifact/status/task event kinds, so the generic SSE name misled. Addresses review feedback on #2085.

github-actions Bot added the size/xl PR size: XL label Aug 24, 2026

tejaskash had a problem deploying to e2e-testing August 24, 2026 17:31 — with GitHub Actions Failure

github-actions Bot added agentcore-harness-reviewing AgentCore Harness review in progress and removed agentcore-harness-reviewing AgentCore Harness review in progress labels Aug 24, 2026

tejaskash mentioned this pull request Aug 24, 2026

feat(dev): wire the Agent Inspector into project dev #2086

Open

github-actions Bot added size/xl PR size: XL and removed size/xl PR size: XL labels Aug 24, 2026

tejaskash had a problem deploying to e2e-testing August 24, 2026 18:08 — with GitHub Actions Failure

tejaskash force-pushed the feat/inspector-agent-proxies branch from fcff328 to 013ffe2 Compare August 25, 2026 17:35