improvement(agent-streaming): add way to opt in for workflow executions (#5956)

Author: icecrasher321

apps/docs/content/docs/en/workflows/deployment/agent-events.mdx

@@ -12,21 +12,51 @@ Agent blocks can emit more than answer text while they run: **provider-exposed t
 Sim does **not** invent thinking for providers that do not stream it. Bedrock Converse, many OpenAI-compat models, and non-reasoning chat models stay text-only (plus tools when a live tool loop is wired).
 </Callout>
 
-## Protocol opt-in vs. event gates (public chat / simple SSE)
+## Two independent switches
 
-Sending the header is a statement about the **client**: it understands v1 framing, so answer text can stream live and be retracted with `chunk_reset`. That alone does not expose anything — it only changes cadence, and it applies even when both event policies are off.
+Agent events are governed by two things that do not depend on each other.
 
-Thinking and tool frames need the header **plus** their own deployment policy:
+**Policy decides which frames exist.** `includeThinking` turns on `thinking` frames, `includeToolCalls` turns on `tool` frames, and both default to **off**.
 
-1. Thinking frames require chat `includeThinking` (default **off**).
-2. Tool lifecycle frames require chat `includeToolCalls` (default **off**).
-3. Both require the request to opt in with:
+| Surface | Policy source |
+|---------|---------------|
+| Deployed chat (`/api/chat/{identifier}`) | The chat deployment's **Thinking** and **Tool calls** toggles |
+| Workflow API (`/api/workflows/{id}/execute`) | Per-request `includeThinking` / `includeToolCalls` in the body |
+
+**The header declares the protocol version.** Sending it says the client understands v1 framing:
 
 ```http
 X-Sim-Stream-Protocol: agent-events-v1
 ```
 
-Legacy clients that omit the header keep today’s text-only SSE even if either deployment policy is enabled. The hosted chat UI always sends the header for its own deployments, so hosted chats stream token by token regardless of the toggles.
+It does two things. It switches answer text to live token-by-token `chunk` frames that `chunk_reset` can retract, and it is **required** for any `thinking` or `tool` frame — a client that never declared a version has no contract for their shape, so it keeps the text-only stream it already understands.
+
+Omitting the header is always valid and always safe: you get settled final-turn text and no agent-event frames, which is what every pre-existing integration receives. The response echoes the header back when the protocol was negotiated.
+
+The header alone exposes nothing, so a chat with both policies off still streams token by token.
+
+<Callout type="warn">
+On the workflow API, setting `includeThinking` or `includeToolCalls` **without** the header is rejected with `400`. The flags would otherwise be a silent no-op, which is the failure mode this protocol exists to avoid. Deployed chat degrades instead of rejecting, because there the policy comes from the deployment rather than the request.
+</Callout>
+
+### Workflow API
+
+```bash
+curl -N https://sim.ai/api/workflows/{id}/execute \
+  -H "X-API-Key: $SIM_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "X-Sim-Stream-Protocol: agent-events-v1" \
+  -d '{
+    "stream": true,
+    "selectedOutputs": ["agent_1.content"],
+    "includeThinking": true,
+    "includeToolCalls": true
+  }'
+```
+
+Both flags default to `false`, so an existing integration receives exactly the frames it does today. The header is required whenever either flag is set; omit it and the request is rejected with `400` rather than silently downgraded.
+
+Two differences from deployed chat are worth knowing. Tool frames carry the name and status only on both surfaces, but the API's terminal `final` envelope keeps tool **arguments and results** — public chat redacts them. And thinking is delivered only as `thinking` frames; it is stripped from `providerTiming.timeSegments` in the envelope on every surface, so enabling the policy is the only way to receive it.
 
 ## Simple SSE frame shapes
 
@@ -47,8 +77,8 @@ Answer text stays on `chunk`. Thinking and tools never reuse `chunk` (so older c
 
 During a live tool loop, the model can’t be classified mid-turn: text it emits may turn out to be the final answer or preamble before a tool call (the stop reason arrives only at turn end).
 
-- **Opted-in clients** (protocol header; no event policy required) receive answer text as `chunk` frames **live**, token by token. If the turn then resolves to tool calls, a `chunk_reset` frame tells the client to discard that block’s streamed text — the final turn re-streams live after tools settle. Append `chunk`, honor `chunk_reset`, and the displayed answer always converges to the block’s final content.
-- **Legacy clients** (no header) never see provisional text: only settled final-turn text is emitted as `chunk`, delivered in one piece when the turn completes. Honoring `chunk_reset` is what buys live cadence, so send the header if you want it.
+- **Clients sending the protocol header** (no event policy required) receive answer text as `chunk` frames **live**, token by token. If the turn then resolves to tool calls, a `chunk_reset` frame tells the client to discard that block’s streamed text — the final turn re-streams live after tools settle. Append `chunk`, honor `chunk_reset`, and the displayed answer always converges to the block’s final content.
+- **Clients without the header** never see provisional text: only settled final-turn text is emitted as `chunk`, delivered in one piece when the turn completes. Honoring `chunk_reset` is what buys live cadence, so send the header if you want it.
 
 Logs, memory, and the block’s `content` output always contain final-turn text only — intermediate preamble is never persisted.
 
@@ -62,7 +92,7 @@ Canvas execution-events `stream:chunk`, `stream:chunk_reset`, `stream:thinking`,
 
 ## Canvas (draft Run)
 
-When you click **Run** in the builder, the execution-events SSE path forwards the same sink. The canvas is always opted in — it does not send (or need) the `X-Sim-Stream-Protocol` header; the dual gate applies only to the public chat / simple SSE surface:
+When you click **Run** in the builder, the execution-events SSE path forwards the same sink. The canvas is always opted in — it does not send (or need) the `X-Sim-Stream-Protocol` header, and the policy switches do not apply to it:
 
 - `stream:thinking` — `{ blockId, text }`
 - `stream:tool` — `{ blockId, phase, id, name, status? }`
@@ -73,7 +103,7 @@ The terminal output panel shows Thinking / Tools chrome above the block output w
 
 ## Chat deployment toggles
 
-In **Deploy → Chat**, enable **Include thinking** for provider-exposed thinking and **Include tool calls** for tool names and lifecycle status. The switches are independent, and both event types still require the protocol header. Neither switch affects answer-text cadence.
+In **Deploy → Chat**, enable **Include thinking** for provider-exposed thinking and **Include tool calls** for tool names and lifecycle status. The switches are independent of each other, and both still require the client to send the protocol header. Neither switch affects answer-text cadence.
 
 Tool arguments and results are never exposed to a public chat — not in lifecycle frames, and not through the terminal `final` envelope, where the block's own tool calls are reduced to the same name-and-lifecycle shape. The authenticated workflow API still returns full tool results. Redeploy or update the chat after changing Agent models or tools.
 
@@ -89,6 +119,68 @@ Per-model support is generated from the model registry on the [Agent block page]
 | OpenAI-compat (Groq, DeepSeek, …) | Only if vendor streams `reasoning` / `reasoning_content` | Live loop where wired (e.g. Groq, DeepSeek) |
 | Bedrock | Not invented | Yes when streaming tool loop is used |
 
+## Consuming the stream
+
+A conforming client owes the stream four things:
+
+1. **Discriminate before appending.** Only a frame with **no** `event` field is answer text. Checking `event === undefined` rather than "has a `chunk` field" is what keeps future frame types from leaking into the answer.
+2. **Accumulate per `blockId`.** A workflow can stream more than one block; frames interleave.
+3. **Honor `chunk_reset`** if you sent the protocol header. Clear that block's accumulated text — it belonged to a turn that resolved to tool calls, and the final turn re-streams.
+4. **Stop at the terminal frame.** Exactly one of `final` or `error` arrives, followed by the literal `"[DONE]"` sentinel. `stream_error` is *not* terminal.
+
+### Reference client
+
+```ts
+type Frame = Record<string, unknown>
+
+async function consume(response: Response) {
+  const reader = response.body!.getReader()
+  const decoder = new TextDecoder()
+  const answers = new Map<string, string>()
+  const thinking = new Map<string, string>()
+  let buffer = ''
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+
+    // SSE frames are newline-delimited; keep the trailing partial line.
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? ''
+
+    for (const line of lines) {
+      if (!line.startsWith('data: ')) continue
+      const payload = line.slice(6)
+
+      const frame = JSON.parse(payload) as Frame | string
+      if (frame === '[DONE]') return { answers, thinking }
+
+      const { blockId, event } = frame as { blockId?: string; event?: string }
+
+      if (event === undefined && typeof frame.chunk === 'string') {
+        answers.set(blockId!, (answers.get(blockId!) ?? '') + frame.chunk)
+      } else if (event === 'chunk_reset') {
+        answers.set(blockId!, '')
+      } else if (event === 'thinking') {
+        thinking.set(blockId!, (thinking.get(blockId!) ?? '') + String(frame.data))
+      } else if (event === 'tool') {
+        // frame.phase is 'start' | 'end'; frame.status is set on 'end'.
+        renderToolChip(frame)
+      } else if (event === 'final') {
+        // Terminal. frame.data.success may be false with frame.data.error.
+      } else if (event === 'error') {
+        throw new Error(String(frame.error))
+      } else if (event === 'stream_error') {
+        // Non-terminal: log and keep reading.
+      }
+    }
+  }
+}
+```
+
+Unknown `event` values should be ignored rather than treated as errors — that is what lets new frame types ship without breaking existing clients.
+
 ## Example (public chat)
 
 <Tabs items={['cURL']}>

apps/docs/content/docs/en/workflows/deployment/api.mdx

@@ -237,6 +237,28 @@ while (true) {
   </Tab>
 </Tabs>
 
+#### Streaming agent thinking and tool calls
+
+By default a streaming run carries answer text only. To also receive the Agent block's reasoning and its tool-call lifecycle, set `includeThinking` / `includeToolCalls`:
+
+```bash
+curl -N -X POST https://sim.ai/api/workflows/{workflow-id}/execute \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $SIM_API_KEY" \
+  -H "X-Sim-Stream-Protocol: agent-events-v1" \
+  -d '{
+    "input": "Research this topic",
+    "stream": true,
+    "selectedOutputs": ["agent_1.content"],
+    "includeThinking": true,
+    "includeToolCalls": true
+  }'
+```
+
+The `X-Sim-Stream-Protocol` header is **required** whenever either flag is set — it declares that your client understands agent-event framing. Setting a flag without it returns `400` rather than silently ignoring the flag. The header also switches answer text to live token-by-token delivery that `chunk_reset` can retract.
+
+Both flags default to `false` and the header is optional on its own, so existing integrations keep the exact frames they receive today. Tool frames carry the tool name and status only; arguments and results arrive in the terminal `final` envelope. Not every model exposes thinking. See [Agent stream events](/docs/workflows/deployment/agent-events) for the frame shapes, a reference client, and per-provider support.
+
 #### Oversized outputs
 
 Workflow execution responses are capped by platform request and response limits. When an internal output, log field, streamed field, or async status payload contains a value that is too large to inline, Sim may replace that nested value with a versioned reference:
@@ -378,6 +400,7 @@ For detailed rate limit information and the logs/webhooks API, see [External API
   { question: "Can I deploy the same workflow as both an API and a chat?", answer: "Yes. A workflow can be simultaneously deployed as an API, chat, MCP tool, and more. Each deployment type runs against the same active snapshot." },
   { question: "How do I choose between sync, streaming, and async?", answer: "Use sync for quick workflows that finish in seconds. Use streaming when you want to show progressive output to users as it's generated. Use async for long-running workflows where holding a connection open isn't practical." },
   { question: "How do I select multiple outputs for streaming?", answer: "Open the Select outputs dropdown in the API tab and check each output field you want to stream. You can choose fields from multiple blocks. The selected fields are reflected as an array in the selectedOutputs request body parameter." },
+  { question: "Can I stream an Agent block's thinking and tool calls over the API?", answer: "Yes. Set includeThinking and/or includeToolCalls to true in the request body and send the X-Sim-Stream-Protocol: agent-events-v1 header, which declares that your client understands agent-event framing. Setting a flag without the header returns 400 rather than silently ignoring it. Both flags default to false, so existing integrations are unaffected. Thinking arrives as thinking frames and tool lifecycle as tool frames carrying name and status only — tool arguments and results stay in the final envelope." },
   { question: "How does Promote to live work?", answer: "Promote to live sets an older version as the active deployment without creating a new version. Subsequent API calls immediately run against the promoted snapshot. This is the fastest way to roll back to a previous state." },
   { question: "How long are async job results available?", answer: "Completed and failed job results are retained for 24 hours. After that, the status endpoint returns 404. Retrieve and store results on your end if you need them longer." },
   { question: "What happens if my API key is compromised?", answer: "Revoke the key immediately in Settings → Sim Keys and generate a new one. Revoked keys stop working instantly." },

apps/sim/app/api/chat/[identifier]/otp/route.ts

@@ -212,7 +212,7 @@ export const PUT = withRouteHandler(
         authType: deployment.authType,
         outputConfigs: deployment.outputConfigs,
         includeThinking: deployment.includeThinking ?? false,
-        includeToolCalls: deployment.includeToolCalls ?? deployment.includeThinking ?? false,
+        includeToolCalls: deployment.includeToolCalls ?? false,
       })
       setChatAuthCookie(response, deployment.id, deployment.authType, deployment.password)
 

apps/sim/app/api/chat/[identifier]/route.test.ts

@@ -413,7 +413,11 @@ describe('Chat Identifier API Route', () => {
       )
     }, 10000)
 
-    it('preserves the legacy tool policy when includeToolCalls is null', async () => {
+    /**
+     * A row predating the column has no tool policy, so it has not opted in.
+     * Thinking must not drag tool frames along with it.
+     */
+    it('reads a null tool policy as off rather than inheriting thinking', async () => {
       const thinkingChatResult = [
         { ...mockChatResult[0], includeThinking: true, includeToolCalls: null },
       ]
@@ -447,7 +451,7 @@ describe('Chat Identifier API Route', () => {
       const options = vi.mocked(createStreamingResponse).mock.calls[0][0]
       expect(options.streamConfig).toMatchObject({
         includeThinking: true,
-        includeToolCalls: true,
+        includeToolCalls: false,
       })
 
       await options.executeFn({
@@ -458,7 +462,7 @@ describe('Chat Identifier API Route', () => {
       const executeOptions = vi.mocked(executeWorkflow).mock.calls[0][4]
       expect(executeOptions).toMatchObject({
         includeThinking: true,
-        includeToolCalls: true,
+        includeToolCalls: false,
         agentEvents: true,
       })
     }, 10000)
@@ -513,7 +517,11 @@ describe('Chat Identifier API Route', () => {
       })
     }, 10000)
 
-    it('keeps agent events off when the protocol header is missing, even with policy on', async () => {
+    /**
+     * Chat degrades rather than rejecting: the policy comes from the
+     * deployment, so an un-negotiated client made no bad request.
+     */
+    it('keeps agent events off without the protocol header, even with policy on', async () => {
       const thinkingChatResult = [
         { ...mockChatResult[0], includeThinking: true, includeToolCalls: false },
       ]

apps/sim/app/api/chat/[identifier]/route.ts

@@ -40,7 +40,7 @@ function toChatConfigResponse(deployment: ChatConfigSource) {
     authType: deployment.authType,
     outputConfigs: deployment.outputConfigs,
     includeThinking: deployment.includeThinking ?? false,
-    includeToolCalls: deployment.includeToolCalls ?? deployment.includeThinking ?? false,
+    includeToolCalls: deployment.includeToolCalls ?? false,
   }
 }
 
@@ -281,7 +281,7 @@ export const POST = withRouteHandler(
         }
 
         const includeThinking = deployment.includeThinking ?? false
-        const includeToolCalls = deployment.includeToolCalls ?? includeThinking
+        const includeToolCalls = deployment.includeToolCalls ?? false
         const agentEvents = shouldEmitAgentStreamEvents({
           includeThinking,
           includeToolCalls,

apps/sim/app/api/chat/manage/[id]/route.test.ts

@@ -160,7 +160,8 @@ describe('Chat Edit API Route', () => {
       expect(data.title).toBe('Test Chat')
       expect(data.chatUrl).toBe('http://localhost:3000/chat/test-chat')
       expect(data.hasPassword).toBe(true)
-      expect(data.includeToolCalls).toBe(true)
+      // Stored null is not an opt-in.
+      expect(data.includeToolCalls).toBe(false)
     })
   })
 
@@ -227,19 +228,17 @@ describe('Chat Edit API Route', () => {
 
       expect(response.status).toBe(200)
       expect(dbChainMockFns.update).toHaveBeenCalled()
+      // An unrelated field update materializes the stored null as false.
       expect(dbChainMockFns.set).toHaveBeenCalledWith(
-        expect.objectContaining({ includeToolCalls: true })
+        expect.objectContaining({ includeToolCalls: false })
       )
       const data = await response.json()
       expect(data.id).toBe('chat-123')
       expect(data.chatUrl).toBe('http://localhost:3000/chat/test-chat')
       expect(data.message).toBe('Chat deployment updated successfully')
     })
 
-    it('turns grandfathered tool calls off when the same update disables thinking', async () => {
-      // Before includeToolCalls existed, includeThinking gated tool frames too.
-      // Resolving the fallback against the stored value would materialize the
-      // stale `true` and silently leave tool frames on.
+    it('leaves tool calls off when a row without a tool policy disables thinking', async () => {
       authMockFns.mockGetSession.mockResolvedValue({ user: { id: 'user-id' } })
 
       mockCheckChatAccess.mockResolvedValue({