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

mkmeral · 2026-03-20T23:22:27Z

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


+## Wire-Safe Serialization (TypeScript)
+
+When streaming events over the wire (SSE, WebSockets, HTTP responses), each event in TypeScript carries a reference to the full `Agent` instance — including conversation history, app state, model configuration, and internal registries. Calling `JSON.stringify(event)` without serialization control would produce massively bloated output that grows with conversation length.


@agent-of-mkmeral this is too long. we don't have to explain everything (internals etc). look at other docs. we should explain that during serialization, we remove some fields. they can directly programmatically access.

also keep the events, so customers can see what we actually export/where

Thanks for the feedback! Pushed a fix in 994c75f — condensed the section significantly:

Removed the verbose "How It Works", "Excluded Fields", "Error Handling", and "In-Process Access" subsections

Now a single concise paragraph explaining that agent, tool, cancel, retry are excluded during serialization and are still available for direct programmatic access

Kept the events table so customers can see what each event serializes to

Went from ~73 lines → ~30 lines. Let me know if it needs further trimming.

Follow-up push in 0a332ee addressing the remaining feedback on this thread (serialization framing + TS tab). Should be good now — please take another look when you get a chance.

- 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-21T00:32:21.621Z

mkmeral

@agent-of-mkmeral

mkmeral · 2026-03-21T00:55:23Z

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


+## Wire-Safe Serialization (TypeScript)
+
+When streaming events over the wire (SSE, WebSockets, HTTP responses), TypeScript events are automatically serialized to compact JSON. Fields like `agent`, `tool`, `cancel`, and `retry` are excluded from serialization since they contain large internal references or mutable control flags — these fields are still available for direct programmatic access in-process.


talk less about wire, more about serialization. (e..g when streaming events are serialized ...).

also dont talk about what we exclude but what we keep. (you can also mention the rest ofc). Essentially this behavior enables below

Done in 0a332ee:

Renamed section to "Event Serialization" (dropped "wire-safe" language)

Reframed the opening to lead with what each event keeps: "each event keeps its type discriminator along with the relevant data fields"

The serialized fields table comes first — showing customers exactly what they get

Excluded fields (agent, tool, cancel, retry) moved to a brief note after the table

mkmeral · 2026-03-21T00:55:44Z

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

 </Tab>
 </Tabs>

+## Wire-Safe Serialization (TypeScript)


this whole section should be in TS tab

Done — the whole section is now wrapped in <Tabs> with:

Python tab: brief note that events are dicts and serialize directly with json.dumps()

TypeScript tab: the full serialization table + code example

…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.

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

Open

mkmeral reviewed Mar 20, 2026

View reviewed changes

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

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

mkmeral reviewed Mar 21, 2026

View reviewed changes

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 requested a deployment to manual-approval March 21, 2026 15:00 — 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 4 commits intostrands-agents:mainfrom
agent-of-mkmeral:docs/wire-safe-streaming-serialization

agent-of-mkmeral commented Mar 20, 2026

Uh oh!

mkmeral Mar 20, 2026

Uh oh!

agent-of-mkmeral Mar 21, 2026

Uh oh!

agent-of-mkmeral Mar 21, 2026

Uh oh!

github-actions bot commented Mar 21, 2026

Uh oh!

mkmeral left a comment

Uh oh!

mkmeral Mar 21, 2026

Uh oh!

agent-of-mkmeral Mar 21, 2026

Uh oh!

mkmeral Mar 21, 2026

Uh oh!

agent-of-mkmeral Mar 21, 2026

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Wire-Safe Serialization (TypeScript)

		When streaming events over the wire (SSE, WebSockets, HTTP responses), each event in TypeScript carries a reference to the full `Agent` instance — including conversation history, app state, model configuration, and internal registries. Calling `JSON.stringify(event)` without serialization control would produce massively bloated output that grows with conversation length.

Conversation

agent-of-mkmeral commented Mar 20, 2026

Description

Changes

Related Issues

Type of Change

Checklist

Uh oh!

mkmeral Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

agent-of-mkmeral Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

agent-of-mkmeral Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 21, 2026

Documentation Preview Ready

Uh oh!

mkmeral left a comment

Choose a reason for hiding this comment

Uh oh!

mkmeral Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

agent-of-mkmeral Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

mkmeral Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

agent-of-mkmeral Mar 21, 2026

Choose a reason for hiding this comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants