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

src/content/docs/user-guide/concepts/streaming/async-iterators.ts

@@ -41,6 +41,9 @@ async function expressExample() {
     })
 
     for await (const event of agent.stream(prompt)) {
+      // Events automatically serialize to compact, wire-safe JSON via toJSON().
+      // Only relevant data fields are included — the full Agent instance,
+      // Tool classes, and mutable hook flags (cancel/retry) are excluded.
       res.write(`${JSON.stringify(event)}\n`)
     }
     res.end()
@@ -51,4 +54,4 @@ async function expressExample() {
   app.post('/stream', handleStreamRequest)
   app.listen(3000)
   // --8<-- [end:express_example]
-}
+}

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

@@ -179,6 +179,37 @@ See [Graph streaming](../multi-agent/graph.md#streaming-events) and [Swarm strea
 </Tab>
 </Tabs>
 
+## 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.
+
+```typescript
+for await (const event of agent.stream('Hello')) {
+  // Automatically serialized to compact, wire-safe JSON
+  res.write(`data: ${JSON.stringify(event)}\n\n`)
+}
+```
+
+### Serialized Event Fields
+
+Each serialized event includes a `type` discriminator and its relevant data fields:
+
+| Event | Serialized fields |
+|---|---|
+| `ModelStreamUpdateEvent` | `{ type, event }` |
+| `ContentBlockEvent` | `{ type, contentBlock }` |
+| `ModelMessageEvent` | `{ type, message, stopReason }` |
+| `ToolResultEvent` | `{ type, result }` |
+| `ToolStreamUpdateEvent` | `{ type, event }` |
+| `AgentResultEvent` | `{ type, result }` |
+| `MessageAddedEvent` | `{ type, message }` |
+| `BeforeToolCallEvent` | `{ type, toolUse }` |
+| `AfterToolCallEvent` | `{ type, toolUse, result, error? }` |
+| `AfterModelCallEvent` | `{ type, stopData?, error? }` |
+| `BeforeToolsEvent` / `AfterToolsEvent` | `{ type, message }` |
+| Lifecycle events (`InitializedEvent`, `BeforeInvocationEvent`, `AfterInvocationEvent`, `BeforeModelCallEvent`) | `{ type }` |
+
+
 ## Quick Examples
 <Tabs>
 <Tab label="Python">
@@ -346,4 +377,4 @@ orchestrator_callback("What is 3+3?")
 
 - Learn about [Async Iterators](async-iterators.md) for asynchronous streaming
 - Explore [Callback Handlers](callback-handlers.md) for synchronous event processing
-- See the [Agent API Reference](@api/python/strands.agent.agent) for complete method documentation
+- See the [Agent API Reference](@api/python/strands.agent.agent) for complete method documentation