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.

mkmeral · 2026-03-27T14:41:26Z

/strands review

agent-of-mkmeral

Review — `/strands review`

Overall: Looks good to me ✅ — clean addition, well-structured, all previous feedback addressed.

Summary

Aspect	Status
CI	✅ Green
All 3 review threads	✅ Resolved
Placement	✅ `### Event Serialization` under Event Types, before Quick Examples
Consistency	✅ Uses `<Tabs>` pattern matching rest of page
Files changed	2 files, +81/-2 lines

What's Good

TypeScript tab — Clear explanation of toJSON() mechanics. The code example with inline comments showing in-process vs serialized output is really instructive. Leads with what each event keeps (per earlier feedback).
Python tab — The filter_event() helper is practical and actionable. Since Python events are plain dicts with no built-in serialization filter, showing a concrete pattern users can adapt is the right call.
async-iterators.ts — The 3-line comment on the JSON.stringify(event) call adds context without being noisy.

Minor Nits (non-blocking)

"wire-safe" in async-iterators.ts comment — The code comment says "Events automatically serialize to compact, wire-safe JSON via toJSON()". Earlier feedback asked to prefer "serialization" language over "wire" language. Consider:
```
// Events automatically serialize to compact JSON via toJSON().
```
(Drop "wire-safe" to stay consistent with the main docs section title "Event Serialization".)
Python tab existence — Previous feedback said "I don't want a tab for python". The content is completely rewritten now (the incorrect info is gone, replaced with a useful filter_event pattern), so this is likely fine — but flagging in case @mkmeral still prefers no Python tab here.

Neither nit is blocking. PR is ready for maintainer approval.

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

agent-of-mkmeral commented Mar 27, 2026

View reviewed changes

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!

mkmeral commented Mar 27, 2026

Uh oh!

agent-of-mkmeral left a comment

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!

mkmeral commented Mar 27, 2026

Uh oh!

agent-of-mkmeral left a comment

Choose a reason for hiding this comment

Review — /strands review

Summary

What's Good

Minor Nits (non-blocking)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Mar 21, 2026 •

edited

Loading

Review — `/strands review`