From 0a21e8b2a5d577cf79c8d98d9d559c3693f508c1 Mon Sep 17 00:00:00 2001 From: Darren Apfel Date: Mon, 24 Aug 2026 20:13:48 -0700 Subject: [PATCH 1/2] docs: fix the install instructions and stale endpoint, add a status section The README's only documented install path was a GitHub branch reference ('deepgram/browser-agent#main'). That install cannot work: dist/ is gitignored and there is no prepare script, so npm delivers only LICENSE, README.md, and package.json, and the entry point dist/index.mjs does not exist (verified in a clean-room install on 2026-08-24). Meanwhile the package has been on the npm registry since 2025 (currently 0.2.1) and installs and bundles correctly from there. Changes: - Installation now instructs 'npm install @deepgram/browser-agent' and explains why the GitHub reference fails. - The 'url' attribute doc pointed at https://api.deepgram.com/v1/agent, contradicting the working example at the top of the same README; it now matches the current endpoint, wss://agent.deepgram.com/v1/agent/converse. - A Status section states the experimental, pre-1.0 nature of the components, names @deepgram/sdk as the supported production path, and points to @deepgram/agents-widget as the more recent embeddable layer. Validated: clean-room npm-registry install bundles under Vite 8; clean-room GitHub-reference install reproduces the failure this README no longer recommends. Co-Authored-By: Claude Fable 5 --- README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index caed342..1029059 100644 --- a/README.md +++ b/README.md @@ -7,14 +7,20 @@ A pair of experimental web components for integrating with Deepgram's Voice Agen - The hoop component is the animation, standalone. More useful when you've got your own rules for socket integration, and just want the look and feel! +## Status + +These components are experimental and pre-1.0, and interfaces may change between versions. For a production integration with the [Deepgram Voice Agent API](https://developers.deepgram.com/docs/voice-agent), the documented and supported path is the official JavaScript SDK, [`@deepgram/sdk`](https://github.com/deepgram/deepgram-js-sdk). If you want an embeddable, framework-free widget rather than a bare web component, see [`@deepgram/agents-widget`](https://github.com/deepgram/agent), which is the more recent embeddable layer. + ## Installation -Install via github by adding to your package.json dependencies: +Install from the npm registry: -```json - "@deepgram/browser-agent": "deepgram/browser-agent#main", +```bash +npm install @deepgram/browser-agent ``` +Installing from a GitHub reference (for example `"@deepgram/browser-agent": "deepgram/browser-agent#main"` in your package.json dependencies) does not work: the repository does not commit its build output and has no prepare script, so a GitHub install delivers a package without its entry point. + ## Using the main component Import the library anywhere for the component to be registered to `deepgram-agent`: @@ -66,7 +72,7 @@ Attributes section. development you may find it more convenient to use an API key (`token` scheme). **Never use API keys in a production browser application!** - `url` (required): The API url - - Chances are you'll set this to `"https://api.deepgram.com/v1/agent"`! + - Chances are you'll set this to `"wss://agent.deepgram.com/v1/agent/converse"`, as in the example above. - `idle-timeout-ms` (optional): how long to wait for user idleness before closing the socket - Timer starts whenever the user is expected to speak (meaning right when opening the connection, and right after each `AgentAudioDone` event). From e5891712a3ccf5c63836fd6134d0e07fc4c68a43 Mon Sep 17 00:00:00 2001 From: Darren Apfel Date: Mon, 31 Aug 2026 08:01:16 -0700 Subject: [PATCH 2/2] docs: neutral status wording variant, held for positioning alignment Removes the positioning claims from the Status sections (the experimental label where it editorializes, and the steering of production integrations to @deepgram/sdk) while keeping the factual parts: pre-1.0, interfaces may change, release cadence, and the sibling-package map. Staged as a variant for the wording-alignment conversation Corey Weathers asked for; not pushed. Co-Authored-By: Claude Fable 5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1029059..3201864 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ A pair of experimental web components for integrating with Deepgram's Voice Agen ## Status -These components are experimental and pre-1.0, and interfaces may change between versions. For a production integration with the [Deepgram Voice Agent API](https://developers.deepgram.com/docs/voice-agent), the documented and supported path is the official JavaScript SDK, [`@deepgram/sdk`](https://github.com/deepgram/deepgram-js-sdk). If you want an embeddable, framework-free widget rather than a bare web component, see [`@deepgram/agents-widget`](https://github.com/deepgram/agent), which is the more recent embeddable layer. +These components are pre-1.0, and interfaces may change between versions. If you want an embeddable, framework-free widget rather than a bare web component, see [`@deepgram/agents-widget`](https://github.com/deepgram/agent), which is the more recent embeddable layer. ## Installation