Skip to content

Commit 01b4412

Browse files
committed
docs(sdk): clarify sendAction semantics for actions-not-turns
Update the sendAction docstrings on TriggerChatTransport (browser) and AgentChat (server) to reflect TRI-9118: actions fire hydrateMessages and onAction only — no run(), no turn lifecycle hooks. The returned stream is empty for void onAction returns and carries the model response when onAction returns a StreamTextResult.
1 parent 4eb252c commit 01b4412

2 files changed

Lines changed: 18 additions & 7 deletions

File tree

packages/trigger-sdk/src/v3/chat-client.ts

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -468,14 +468,22 @@ export class AgentChat<TAgent = unknown> {
468468
/**
469469
* Send a custom action to the agent.
470470
*
471-
* Actions wake the agent, fire the `onAction` hook (which can modify
472-
* conversation history via `chat.history.*`), then trigger a normal
473-
* `run()` turn so the LLM responds to the updated state.
471+
* Actions are not turns. They wake the agent, fire `hydrateMessages`
472+
* (if configured) and `onAction` only — no `onTurnStart` /
473+
* `prepareMessages` / `onBeforeTurnComplete` / `onTurnComplete`, no
474+
* `run()` invocation.
474475
*
475476
* The action payload is validated against the agent's `actionSchema`
476-
* on the backend.
477+
* on the backend. Use `chat.history.*` inside `onAction` to mutate
478+
* state. To produce a model response from the action, return a
479+
* `StreamTextResult` (or `string` / `UIMessage`) from `onAction` —
480+
* the returned stream is auto-piped over this stream. When `onAction`
481+
* returns `void`, the action is side-effect-only and the returned
482+
* stream completes immediately with `trigger:turn-complete`.
477483
*
478-
* @returns A `ChatStream` for the agent's response.
484+
* @returns A `ChatStream`. For void actions the stream completes
485+
* immediately. For actions that return a model response, the stream
486+
* carries the assistant chunks.
479487
*
480488
* @example
481489
* ```ts

packages/trigger-sdk/src/v3/chat.ts

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -763,8 +763,11 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
763763

764764
/**
765765
* Send a custom action chunk (for `chat.agent`'s `actionSchema` /
766-
* `onAction` hook). Returns the agent's response stream just like
767-
* `sendMessages`.
766+
* `onAction` hook). Actions are not turns — only `hydrateMessages`
767+
* and `onAction` fire on the agent side. The returned stream
768+
* carries any model response `onAction` produced (when it returns a
769+
* `StreamTextResult`); for `void`-returning side-effect-only actions
770+
* the stream completes immediately with `trigger:turn-complete`.
768771
*/
769772
sendAction = async (
770773
chatId: string,

0 commit comments

Comments
 (0)