docs: add wire-safe serialization section for TypeScript streaming events by agent-of-mkmeral · Pull Request #693 · strands-agents/docs

agent-of-mkmeral · 2026-03-20T23:05:37Z

Description

Documents the toJSON() serialization behavior for all TypeScript streaming events. When events are sent over the wire (SSE, WebSockets, HTTP responses), the toJSON() method ensures compact output (~100-200 bytes) instead of serializing the entire Agent instance (~54KB+ per event).

Changes

Streaming Overview (index.mdx): Added new "Wire-Safe Serialization (TypeScript)" section with:
- How toJSON() works with JSON.stringify()
- Complete table of what each event serializes to
- List of excluded fields (agent, tool, cancel, retry)
- Error serialization format ({ error: { message?: string } })
- Code example showing in-process vs wire access patterns
Express.js example (async-iterators.ts): Added comments explaining the automatic wire-safe serialization behavior

Related Issues

feat: add toJSON() to all streaming events for wire-safe serialization sdk-typescript#708 — Implementation PR adding toJSON() to all streaming events
TS streaming events agent-of-mkmeral/strands-coder#41 — Original tracking issue

Type of Change

New content

Checklist

I have read the CONTRIBUTING document
My changes follow the project's documentation style
I have tested the documentation locally using npm run dev
Links in the documentation are valid and working

…ents Document the toJSON() serialization behavior for all TypeScript streaming events. This includes: - New 'Wire-Safe Serialization' section in the streaming overview - Table showing what each event serializes to - Explanation of excluded fields (agent, tool, cancel, retry) - Error handling format ({ error: { message?: string } }) - In-process vs wire access patterns - Updated Express.js example with serialization comments Related: strands-agents/sdk-typescript#708

src/content/docs/user-guide/concepts/streaming/index.mdx

- Remove verbose 'How It Works', 'Excluded Fields', 'Error Handling', and 'In-Process Access' subsections - Keep single concise paragraph explaining serialization behavior - Retain events table showing what each event serializes to - Mention excluded fields (agent, tool, cancel, retry) inline Co-authored-by: mkmeral <mkmeral@users.noreply.github.com>

github-actions · 2026-03-21T00:32:21Z

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-cms-693/docs/user-guide/quickstart/overview/

Updated at: 2026-03-25T19:27:11.158Z

mkmeral

@agent-of-mkmeral

src/content/docs/user-guide/concepts/streaming/index.mdx

…fields Address review feedback: - Rename 'Wire-Safe Serialization (TypeScript)' to 'Event Serialization' - Wrap in <Tabs> with Python/TypeScript tabs - Lead with what each event keeps during serialization - Move excluded fields mention to secondary position after table - Use 'serialization' language instead of 'wire-safe'

mkmeral · 2026-03-21T14:44:54Z

add this under streaming events tabs (that already exist) or something, I don't want a tab for python. also that python info is not correct anyway

mkmeral · 2026-03-21T14:45:04Z

@agent-of-mkmeral

@mkmeral

…nt types Address review feedback from @mkmeral: - Remove Tabs wrapper and Python tab (info was not correct) - Downgrade to ### subsection under Event Types (same level as Lifecycle Events, Model Stream Events, etc.) - TypeScript serialization content stays as-is, directly under heading

agent-of-mkmeral · 2026-03-21T15:00:30Z

Done in f01de2e — addressed both points:

Removed the Python tab (info was incorrect anyway)
Removed the <Tabs> wrapper entirely — the section is now ### Event Serialization (a subsection under Event Types, same level as Lifecycle Events, Model Stream Events, etc.) with just the TypeScript serialization content directly

Net change: -11 lines, +1 line.

…aming-serialization

agent-of-mkmeral · 2026-03-25T14:34:42Z

Merged main into this branch to fix the CI failure.

Root cause: The typecheck:snippets step was failing with:

error TS2307: Cannot find module '@strands-agents/sdk/openai' or its corresponding type declarations.

in deploy_to_docker/imports.ts and deploy_to_docker/index.ts — completely unrelated to this PR's streaming docs changes. These files were updated on main (likely by a recent rename/refactor of the OpenAI provider module), and this branch was behind.

Fix: Merged upstream main (97aa679) → commit dd35581. No conflicts.

CI should be green now. @mkmeral

Updates Event Serialization section for sdk-typescript PR #741: - Put Event Serialization under Python/TypeScript tabs - Add multi-agent event serialization table (10 events from PR #741) - Add A2A event serialization table (2 events from PR #741) - Add Python tab explaining event filtering approach - Update excluded fields list to include orchestrator and state - Note Error object serialization format

Replace the three comprehensive tables (agent events, multi-agent events, A2A events) in the TypeScript serialization tab with prose that explains the behavior, the key differences during serialization, and mentions a few examples of filtered/included fields without an exhaustive listing. Python tab remains unchanged.

Show what an event looks like in-process (with agent reference) versus what JSON.stringify produces (compact wire-safe output). Covers text deltas, lifecycle events, and result events.

Removed commented-out code regarding lifecycle and result events.

agent-of-mkmeral requested a deployment to manual-approval March 20, 2026 23:05 — with GitHub Actions Waiting

agent-of-mkmeral had a problem deploying to manual-approval March 20, 2026 23:05 — with GitHub Actions Error

agent-of-mkmeral mentioned this pull request Mar 20, 2026

feat: add toJSON() to all streaming events for wire-safe serialization strands-agents/sdk-typescript#708

Merged

mkmeral reviewed Mar 20, 2026

View reviewed changes

src/content/docs/user-guide/concepts/streaming/index.mdx Outdated Show resolved Hide resolved

agent-of-mkmeral requested a deployment to manual-approval March 21, 2026 00:00 — with GitHub Actions Waiting

agent-of-mkmeral temporarily deployed to manual-approval March 21, 2026 00:00 — with GitHub Actions Inactive

mkmeral reviewed Mar 21, 2026

View reviewed changes

src/content/docs/user-guide/concepts/streaming/index.mdx Outdated Show resolved Hide resolved

src/content/docs/user-guide/concepts/streaming/index.mdx Outdated Show resolved Hide resolved

agent-of-mkmeral had a problem deploying to manual-approval March 21, 2026 05:27 — with GitHub Actions Error

agent-of-mkmeral requested a deployment to manual-approval March 21, 2026 05:28 — with GitHub Actions Waiting

agent-of-mkmeral had a problem deploying to manual-approval March 21, 2026 15:00 — with GitHub Actions Error

agent-of-mkmeral requested a deployment to manual-approval March 21, 2026 15:00 — with GitHub Actions Waiting

Merge remote-tracking branch 'upstream/main' into docs/wire-safe-stre…

dd35581

…aming-serialization

agent-of-mkmeral requested a deployment to manual-approval March 25, 2026 15:53 — with GitHub Actions Waiting

agent-of-mkmeral temporarily deployed to manual-approval March 25, 2026 15:53 — with GitHub Actions Inactive

agent-of-mkmeral temporarily deployed to manual-approval March 25, 2026 17:49 — with GitHub Actions Inactive

agent-of-mkmeral requested a deployment to manual-approval March 25, 2026 17:49 — with GitHub Actions Waiting

docs: add descriptive comments to TS serialization code sample

b864926

Show what an event looks like in-process (with agent reference) versus what JSON.stringify produces (compact wire-safe output). Covers text deltas, lifecycle events, and result events.

agent-of-mkmeral had a problem deploying to manual-approval March 25, 2026 18:08 — with GitHub Actions Error

agent-of-mkmeral requested a deployment to manual-approval March 25, 2026 18:08 — with GitHub Actions Waiting

Clean up commented code in streaming index

de103df

Removed commented-out code regarding lifecycle and result events.

mkmeral deployed to manual-approval March 25, 2026 19:22 — with GitHub Actions Active

mkmeral requested a deployment to manual-approval March 25, 2026 19:22 — with GitHub Actions Waiting

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add wire-safe serialization section for TypeScript streaming events#693

docs: add wire-safe serialization section for TypeScript streaming events#693
agent-of-mkmeral wants to merge 9 commits intostrands-agents:mainfrom
agent-of-mkmeral:docs/wire-safe-streaming-serialization

agent-of-mkmeral commented Mar 20, 2026

Uh oh!

Uh oh!

github-actions bot commented Mar 21, 2026 •

edited

Loading

Uh oh!

mkmeral left a comment

Uh oh!

Uh oh!

Uh oh!

mkmeral commented Mar 21, 2026

Uh oh!

mkmeral commented Mar 21, 2026

Uh oh!

agent-of-mkmeral commented Mar 21, 2026

Uh oh!

agent-of-mkmeral commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

agent-of-mkmeral commented Mar 20, 2026

Description

Changes

Related Issues

Type of Change

Checklist

Uh oh!

Uh oh!

github-actions bot commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Preview Ready

Uh oh!

mkmeral left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mkmeral commented Mar 21, 2026

Uh oh!

mkmeral commented Mar 21, 2026

Uh oh!

agent-of-mkmeral commented Mar 21, 2026

Uh oh!

agent-of-mkmeral commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Mar 21, 2026 •

edited

Loading