Skip to content

feat(aws-strands): add strands typescript sdk integration#1681

Open
cogwirrel wants to merge 1 commit into
ag-ui-protocol:mainfrom
cogwirrel:feat/strands-ts
Open

feat(aws-strands): add strands typescript sdk integration#1681
cogwirrel wants to merge 1 commit into
ag-ui-protocol:mainfrom
cogwirrel:feat/strands-ts

Conversation

@cogwirrel
Copy link
Copy Markdown

Adds a TypeScript adapter under integrations/aws-strands/typescript that mirrors the existing Python adapter as much as possible.

Provides:

  • StrandsAgent wrapping a Strands Agent or multi-agent orchestrator (Graph/Swarm) and translating its streaming events into AG-UI events (text, reasoning, tool calls, tool results, state snapshots, messages snapshots, multi-agent steps, custom events).
  • StrandsAgentConfig / ToolBehavior with camelCase equivalents of every Python hook (stateFromArgs, stateFromResult, customResultHandler, argsStreamer, predictState, sessionManagerProvider, ...).
  • Express transport via addStrandsExpressEndpoint + createStrandsApp, plus addPing and addCapabilities for health + advertised-event matrix.
  • Eight runnable examples matching the Python server (agentic-chat, agentic-chat-reasoning, agentic-chat-multimodal, backend-tool-rendering, shared-state, agentic-generative-ui, human-in-the-loop) plus a TS-only tool-based-generative-ui example, and a dojo server that mounts all eight at the Python reference paths.
  • Injectable Logger (config.logger) with Python-parity debug traces.

Native interrupt bridge (Strands SDK 1.1.0+):

  • AgentResult.stopReason === "interrupt" emits RUN_FINISHED with outcome.type "interrupt" and the outstanding interrupts; IDs are recorded per thread.
  • RunAgentInput.resume[] is validated against pending IDs (interrupts.mdx rule 4) and converted into Strands InterruptResponseContent[] forwarded as the stream args. Unknown IDs short-circuit with UNKNOWN_INTERRUPT.

Key differences vs. the Python adapter:

SDK-forced (behavior unchanged):

  • Typed .type dispatch instead of Python's dict-key matching.
  • AgentConfig.messages seeding at construction time vs. Python's in-place self.messages mutation; drives a separate buildStrandsSeed helper.
  • Hardcoded TemplateAgentCloneFields in place of Python's inspect.signature introspection of StrandsAgentCore.init.

Additive (TS-only, close conformance gaps or match TS ecosystem):

  • Multi-agent orchestrator mode for Strands Graph/Swarm.
  • THREAD_BUSY guard for concurrent runs on the same thread.
  • AbortController wired into Strands cancelSignal so client disconnects cancel the underlying stream.
  • Native Strands interrupt bridge (above).
  • HTTP-edge request validation (415 / 400) via the shared Zod RunAgentInputSchema, with snake_case -> camelCase key normalization.
  • HTTP/1.1 + HTTP/2 disconnect handling that fires iterator.return() so the generator's finally runs (releases THREAD_BUSY slot, aborts stream).
  • Explicit protobuf content negotiation (no binary frames for Accept: /).
  • GET /capabilities endpoint advertising supported events/features.
  • emitChunkEvents collapsing _START/_CONTENT/*_END triples into self-expanding TEXT/TOOL_CALL/REASONING chunks.
  • ToolCallContextExtras exposing context[] + forwardedProps on every hook context and stateContextBuilder.

Dojo wiring:

  • aws-strands-typescript entry in agents.ts, menu.ts, env.ts, the prep/run scripts, and the dojo-e2e.yml CI matrix (port 8022).
  • Feature list is a strict superset of the Python sibling: agentic_chat, agentic_chat_reasoning, agentic_chat_multimodal, v1_agentic_chat, backend_tool_rendering, agentic_generative_ui, shared_state, human_in_the_loop, tool_based_generative_ui.

Closes #1680

Adds a TypeScript adapter under integrations/aws-strands/typescript that
mirrors the existing Python adapter as much as possible.

Provides:
- StrandsAgent wrapping a Strands Agent or multi-agent orchestrator
  (Graph/Swarm) and translating its streaming events into AG-UI events
  (text, reasoning, tool calls, tool results, state snapshots, messages
  snapshots, multi-agent steps, custom events).
- StrandsAgentConfig / ToolBehavior with camelCase equivalents of every
  Python hook (stateFromArgs, stateFromResult, customResultHandler,
  argsStreamer, predictState, sessionManagerProvider, ...).
- Express transport via addStrandsExpressEndpoint + createStrandsApp,
  plus addPing and addCapabilities for health + advertised-event matrix.
- Eight runnable examples matching the Python server (agentic-chat,
  agentic-chat-reasoning, agentic-chat-multimodal, backend-tool-rendering,
  shared-state, agentic-generative-ui, human-in-the-loop) plus a TS-only
  tool-based-generative-ui example, and a dojo server that mounts all
  eight at the Python reference paths.
- Injectable Logger (config.logger) with Python-parity debug traces.

Native interrupt bridge (Strands SDK 1.1.0+):
- AgentResult.stopReason === "interrupt" emits RUN_FINISHED with
  outcome.type "interrupt" and the outstanding interrupts; IDs are
  recorded per thread.
- RunAgentInput.resume[] is validated against pending IDs (interrupts.mdx
  rule 4) and converted into Strands InterruptResponseContent[] forwarded
  as the stream args. Unknown IDs short-circuit with UNKNOWN_INTERRUPT.

Key differences vs. the Python adapter:

SDK-forced (behavior unchanged):
- Typed .type dispatch instead of Python's dict-key matching.
- AgentConfig.messages seeding at construction time vs. Python's in-place
  self.messages mutation; drives a separate buildStrandsSeed helper.
- Hardcoded TemplateAgentCloneFields in place of Python's
  inspect.signature introspection of StrandsAgentCore.__init__.

Additive (TS-only, close conformance gaps or match TS ecosystem):
- Multi-agent orchestrator mode for Strands Graph/Swarm.
- THREAD_BUSY guard for concurrent runs on the same thread.
- AbortController wired into Strands cancelSignal so client disconnects
  cancel the underlying stream.
- Native Strands interrupt bridge (above).
- HTTP-edge request validation (415 / 400) via the shared Zod
  RunAgentInputSchema, with snake_case -> camelCase key normalization.
- HTTP/1.1 + HTTP/2 disconnect handling that fires iterator.return() so
  the generator's finally runs (releases THREAD_BUSY slot, aborts stream).
- Explicit protobuf content negotiation (no binary frames for Accept: */*).
- GET /capabilities endpoint advertising supported events/features.
- emitChunkEvents collapsing *_START/*_CONTENT/*_END triples into
  self-expanding TEXT/TOOL_CALL/REASONING chunks.
- ToolCallContextExtras exposing context[] + forwardedProps on every
  hook context and stateContextBuilder.

Dojo wiring:
- aws-strands-typescript entry in agents.ts, menu.ts, env.ts, the prep/run
  scripts, and the dojo-e2e.yml CI matrix (port 8022).
- Feature list is a strict superset of the Python sibling: agentic_chat,
  agentic_chat_reasoning, agentic_chat_multimodal, v1_agentic_chat,
  backend_tool_rendering, agentic_generative_ui, shared_state,
  human_in_the_loop, tool_based_generative_ui.

Closes ag-ui-protocol#1680
@cogwirrel cogwirrel requested a review from a team as a code owner May 14, 2026 14:38
@vercel
Copy link
Copy Markdown

vercel Bot commented May 14, 2026

@cogwirrel is attempting to deploy a commit to the CopilotKit Team on Vercel.

A member of the Team first needs to authorize it.

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.

[Feature]: [AWS Strands] Support for TypeScript

1 participant