From 5f43df742f011e96f58b62fdbf32e6e99efc2742 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 10 Sep 2026 11:33:47 +0000 Subject: [PATCH 1/2] chore(main): release react 0.2.0 --- .release-please-manifest.json | 2 +- packages/react/CHANGELOG.md | 21 +++++++++++++++++++++ packages/react/package.json | 2 +- 3 files changed, 23 insertions(+), 2 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index c8d2b69..c72360c 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - "packages/react": "0.1.0" + "packages/react": "0.2.0" } diff --git a/packages/react/CHANGELOG.md b/packages/react/CHANGELOG.md index da6892f..f299317 100644 --- a/packages/react/CHANGELOG.md +++ b/packages/react/CHANGELOG.md @@ -1,5 +1,26 @@ # Changelog +## [0.2.0](https://github.com/deepgram/react/compare/react-v0.1.0...react-v0.2.0) (2026-09-10) + + +### ⚠ BREAKING CHANGES + +* **react:** AgentMode now includes "thinking" and public context and hook result types add required members. + +### Features + +* **react:** harden lifecycle and expand agent APIs ([f6a16ac](https://github.com/deepgram/react/commit/f6a16ac1421c74801ae050ca44403b0963e396e8)) + + +### Bug Fixes + +* **react:** address review feedback ([42cc340](https://github.com/deepgram/react/commit/42cc340f1ac3a58c479a7d5e014bad3bb0d79f06)) +* **react:** bundle portable declarations ([7781263](https://github.com/deepgram/react/commit/7781263b03e993a4cab14f60babf4dd4ed324797)) +* **react:** handle manual start failures ([d605460](https://github.com/deepgram/react/commit/d60546083141e193d1fb0da8f23836fcfe472137)) +* **react:** report auto-start failures ([4525294](https://github.com/deepgram/react/commit/4525294791b83c3c7aee4b1a849ec834e38b31ec)) +* **react:** report auto-start failures once ([d0309c4](https://github.com/deepgram/react/commit/d0309c4714b9666a7851e5bf497fa9e29231b1f6)) +* **react:** report automatic microphone failures ([76fa954](https://github.com/deepgram/react/commit/76fa95407e7ea91eb27397b5dce0bae9422d4038)) + ## 0.1.0 (2026-04-30) diff --git a/packages/react/package.json b/packages/react/package.json index d48807d..c5b999b 100644 --- a/packages/react/package.json +++ b/packages/react/package.json @@ -1,6 +1,6 @@ { "name": "@deepgram/react", - "version": "0.1.0", + "version": "0.2.0", "description": "React hooks and components for @deepgram/agents", "type": "module", "main": "dist/index.cjs", From 4482d24fbf733bb69ee76227a1cab128cf84deff Mon Sep 17 00:00:00 2001 From: Greg Holmes Date: Thu, 10 Sep 2026 16:23:10 +0100 Subject: [PATCH 2/2] docs(react): add 0.2 migration guidance --- MIGRATION.md | 98 +++++++++++++++++++++++++++++++++++++ README.md | 3 +- packages/react/CHANGELOG.md | 20 +++++--- packages/react/README.md | 4 ++ 4 files changed, 116 insertions(+), 9 deletions(-) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..9d9e8be --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,98 @@ +# Migration Guide + +## 0.1 to 0.2 + +`@deepgram/react` 0.2.0 adds runtime Voice Agent controls and updates the package for `@deepgram/agents` 0.1.2 and `@deepgram/sdk` 5.9.0. + +Install the new release: + +```bash +npm install @deepgram/react@^0.2.0 +``` + +### Handle the `thinking` mode + +`AgentMode` now includes `"thinking"`. Update exhaustive mode switches and any mode-to-label maps. + +```ts +switch (mode) { + case "idle": + case "listening": + case "thinking": + case "speaking": + break; +} +``` + +### Update typed context and hook wrappers + +`AgentContextValue` and hook result types now include required members for the new controls and state. Components that consume the hooks do not need a source change, but typed mocks, wrappers, and objects that implement these interfaces must provide the new members. + +### Keep the client-tool unsubscribe function + +`registerClientTool()` now returns an unsubscribe function. Existing calls that ignore its return value still work. Store and call the result when registering outside a component lifecycle: + +```tsx +import { useAgentContext } from "@deepgram/react"; + +function MapControls() { + const { registerClientTool } = useAgentContext(); + const unregister = registerClientTool("get_location", () => { + return JSON.stringify({ latitude: 0, longitude: 0 }); + }); + + // Later, when the handler is no longer needed: + unregister(); +} +``` + +`useAgentClientTool()` remains the preferred option inside React components and unregisters automatically on unmount. + +### Treat standalone `start()` as a fresh session + +`useDeepgramAgent().start()` now clears `conversation` before connecting. Keep any transcript that must survive a restart outside the hook, or restore it after the new session starts. + +Manual `start()` calls reject on failure. Handle the returned promise: + +```tsx +import { useAgentControls } from "@deepgram/react"; + +function ConnectButton() { + const { start } = useAgentControls(); + + async function handleStart() { + try { + await start(); + } catch (error) { + console.error("Failed to start the Voice Agent", error); + } + } + + return ; +} +``` + +Automatic start failures, including microphone failures during auto-start and reconnect, call `onSdkError` when it is provided. + +### Use the new runtime controls + +Use the controls from `useAgentControls()`, `useAgentConversation()`, or `useDeepgramAgent()` to update a connected agent without recreating the provider: + +```tsx +import { useAgentControls } from "@deepgram/react"; + +function TakeoverButton() { + const { sendAgentMessage, updatePrompt } = useAgentControls(); + + function takeOver() { + updatePrompt("Keep responses concise."); + sendAgentMessage("I will take it from here.", "interrupt"); + } + + return ; +} +``` + +Use `onListenUpdated`, `onPromptUpdated`, `onSpeakUpdated`, and `onThinkUpdated` on `AgentProvider` or `useDeepgramAgent()` to observe the matching server confirmation. + +See the [package README](packages/react/README.md) for the complete API surface. diff --git a/README.md b/README.md index 40e47d9..c87b8cb 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ function VoiceAgent() { | `useAgentSession` | Direct access to the underlying `AgentSession` (escape hatch) | | `useDeepgramAgent` | Standalone hook -- no provider needed | -See the [package README](packages/react/README.md) for full API documentation. +See the [package README](packages/react/README.md) for full API documentation. See the [migration guide](MIGRATION.md) when upgrading from 0.1 to 0.2. ## Related Packages @@ -84,6 +84,7 @@ See the [package README](packages/react/README.md) for full API documentation. - [Deepgram Voice Agent docs](https://developers.deepgram.com/docs/voice-agent) - [API reference](https://developers.deepgram.com/reference) +- [Migration guide](MIGRATION.md) - [`@deepgram/ui` -- pre-built components](https://github.com/deepgram/ui) ## Development diff --git a/packages/react/CHANGELOG.md b/packages/react/CHANGELOG.md index f299317..b06c1e0 100644 --- a/packages/react/CHANGELOG.md +++ b/packages/react/CHANGELOG.md @@ -5,21 +5,25 @@ ### ⚠ BREAKING CHANGES -* **react:** AgentMode now includes "thinking" and public context and hook result types add required members. +* **react:** `AgentMode` now includes `"thinking"`. +* **react:** Public context and hook result types add required members for the new agent controls and state. +* **react:** `registerClientTool()` now returns an unsubscribe function. +* **react:** `useDeepgramAgent().start()` begins a fresh session and clears `conversation`. ### Features -* **react:** harden lifecycle and expand agent APIs ([f6a16ac](https://github.com/deepgram/react/commit/f6a16ac1421c74801ae050ca44403b0963e396e8)) +* **react:** Add `"thinking"` mode and `isThinking` state. +* **react:** Add `sendAgentMessage()` with `"default"`, `"queue"`, and `"interrupt"` behavior. +* **react:** Add `updateListen()`, `updateThink()`, `updateSpeak()`, and `updatePrompt()` for runtime agent settings changes. +* **react:** Add typed callbacks for protocol notifications, including settings update confirmations. +* **react:** Expose the new controls and state through `AgentProvider`, focused hooks, and `useDeepgramAgent`. ### Bug Fixes -* **react:** address review feedback ([42cc340](https://github.com/deepgram/react/commit/42cc340f1ac3a58c479a7d5e014bad3bb0d79f06)) -* **react:** bundle portable declarations ([7781263](https://github.com/deepgram/react/commit/7781263b03e993a4cab14f60babf4dd4ed324797)) -* **react:** handle manual start failures ([d605460](https://github.com/deepgram/react/commit/d60546083141e193d1fb0da8f23836fcfe472137)) -* **react:** report auto-start failures ([4525294](https://github.com/deepgram/react/commit/4525294791b83c3c7aee4b1a849ec834e38b31ec)) -* **react:** report auto-start failures once ([d0309c4](https://github.com/deepgram/react/commit/d0309c4714b9666a7851e5bf497fa9e29231b1f6)) -* **react:** report automatic microphone failures ([76fa954](https://github.com/deepgram/react/commit/76fa95407e7ea91eb27397b5dce0bae9422d4038)) +* **react:** Harden starts, stops, reconnects, and StrictMode replay so canceled or failed sessions cannot retain stale microphone, playback, or client-tool resources. +* **react:** Report automatic start failures, including microphone failures during auto-start and reconnect, through `onSdkError` or `console.error` when no callback is set. Manual `start()` rejects instead. +* **react:** Publish portable declarations that resolve agent types from `@deepgram/agents` in consumer projects. ## 0.1.0 (2026-04-30) diff --git a/packages/react/README.md b/packages/react/README.md index 85e1de0..32ca692 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -288,6 +288,10 @@ export type { }; ``` +## Migration + +See the [0.1 to 0.2 migration guide](https://github.com/deepgram/react/blob/main/MIGRATION.md) when upgrading an existing integration. + ## License MIT