Alan AI SDK for Web: embedding a voice agent with @alan-ai/alan-sdk-web

What the Alan AI SDK for Web actually does

The repository ships one JavaScript library, published as @alan-ai/alan-sdk-web, whose package description calls it "a lightweight JavaScript library for adding a voice experience to your website or web application". That is the whole of the client side. The README frames the larger product as "Application-Level AI", a system that generates business logic and UI at runtime, but the repository you clone contains the embedding layer, not the generation engine.

The audience is web teams that want a conversational interface without writing speech recognition, intent parsing or text-to-speech themselves. The README's start path assumes you build the dialog script in JavaScript inside Alan AI Studio and then attach it to your app with this SDK. If you are looking for a library that runs a language model locally in the browser, this is not that. The intelligence sits behind Alan's platform, and the SDK is the socket you plug into it.

The client-server split behind the voice button

The SDK is deliberately thin, and the architecture follows from that. Your app loads dist/alan_lib.js, the entry named in package.json, and initialises it with a key that identifies your Alan AI Studio project. From then on the flow is: the user presses the Alan AI button, audio goes to Alan's service, the dialog script you wrote in Studio decides what to do, and the result comes back to the page as an event your code handles.

Because the dialog script lives in Studio rather than in your bundle, you can change what the agent says without redeploying the front end. That is the trade-off in one sentence. You gain a hosted place to iterate on conversation logic, and you give up the ability to run the agent without a network round trip to Alan. The examples folder reflects the split: examples/alan-example-integration-react, examples/alan-example-integration-angular, examples/alan-example-integration-vue, examples/alan-example-integration-ember and examples/alan-example-integration-electron each wire the same client library into a different framework, and the README says to follow the README inside each example folder to launch it.

Installing @alan-ai/alan-sdk-web and wiring a first button

The README's start section does not print install commands; it points to the npm package and to per-framework documentation pages for vanilla JavaScript, React, Angular, Vue, Ember and Electron. The package is on npm, so the install step is the standard one for the ecosystem. Run this in your project root.

npm i @alan-ai/alan-sdk-web

After that you need a key from Alan AI Studio, which the README describes as the place to "build dialog scripts in JavaScript and test them", reached through the sign-up link at studio.alan.app/register. The SDK is then initialised from your application code and the agent is exposed through a button in the page. The exact initialisation call and the button markup differ per framework, and the README routes you to the matching documentation page rather than showing the snippet inline.

The examples are the fastest way to see a working setup. The repository lists eight example apps, including examples/alan-example-app-angular-order-drinks, examples/alan-example-app-react-api-test and examples/alan-example-integeration-react-appointment. Note the spelling of that last folder name before you script a clone; it is written that way in the repository. The README's instruction is to follow the README inside the example folder, then press the Alan AI button and interact with the agent. What you should see after this is a button in the corner of the page; pressing it starts the agent. If nothing appears, the usual cause is a missing or mismatched Studio key, since the button is created by the SDK rather than by your markup.

Where this SDK stops being the right choice

The dependency on Alan's hosted platform is the main limitation, and it is structural rather than a bug. If your application cannot send user audio or text to a third-party service, this SDK has no offline mode to fall back on, because the dialog script it executes lives in Studio. Teams in regulated environments should treat that as a gating question before writing any integration code.

The second constraint is that the client library is small by design. It gives you the connection and the callbacks; it does not give you a local model, a self-hosted runtime or a way to run the conversation logic inside your own process. If your requirement is a chatbot whose behaviour is fully contained in your repository and reviewable in a pull request, the split between Studio and the client is working against you.

Finally, the README is a signpost rather than a manual. It links out to framework documentation and to the examples, and it does not document the callback surface, error handling or what happens when the connection drops. Those details have to come from the documentation site. That is a real cost when you are estimating an integration, because the repository alone will not tell you how the SDK behaves under failure.

How this differs from a self-hosted assistant library

The obvious alternative is a client-side assistant library that runs the whole loop in your own codebase, for example a speech and intent stack you host yourself and call from the browser. The difference is not the feature list; it is where the conversation logic executes. With the Alan AI SDK for Web, the script you edit lives in Alan AI Studio and is interpreted by Alan's service, and the SDK's job is to carry commands and events between that service and your page. With a self-hosted stack, the same logic is code in your repository, deployed with your release cycle, and the network hop disappears.

That changes several practical things. Iteration speed favours Alan, because a dialog change does not require a front-end deploy. Auditability favours the self-hosted route, because every change is a commit. Latency and availability follow the same split: Alan's platform is one more service in the request path, and your own stack is one more service you operate. Neither is free. The choice comes down to whether you would rather maintain conversation logic in a hosted editor or in your own deployment pipeline.

Maintenance, releases and the licence question

The repository is not archived, and the last push was on 2026-08-05, the same day as release v.1.8.142. The two prior releases, v.1.8.141 and v.1.8.140, landed on 2026-07-08 and 2026-07-03, so the version cadence in the recent history is roughly monthly. The package.json in the repository declares version 1.8.143, one ahead of the newest published release listed, which is worth knowing if you pin versions and compare the manifest against the npm tag.

The licence is MIT, stated in package.json. That covers the client library. It does not answer what terms apply to the Alan AI platform itself, which is a separate service reached through alan.app and studio.alan.app. The repository does not carry the platform's terms, so if you need to know how the hosted side is licensed, priced or governed, that has to be checked on Alan's own site. Treat the MIT grant as covering the code you install and nothing more.

Upgrade cost is dominated by the hosted side. Because the dialog script lives in Studio and the SDK is a thin client, an SDK version bump is usually a package update rather than a rewrite, but the callback surface and the button behaviour are defined by the library, and the README does not publish a compatibility matrix between SDK versions and Studio projects. The release notes are the place to look before bumping.

Editorial conclusion

Adopt the Alan AI SDK for Web if your dialog logic can live in Alan AI Studio and you want a voice button in a React, Angular, Vue, Ember, Electron or plain JavaScript app without building speech infrastructure. Do not adopt it if you need the agent to run inside your own network or if you cannot accept a third-party service in the request path. Before committing, verify the licence terms and the current pricing of the Alan AI platform on alan.app, and confirm the SDK version you install matches the Studio project you build against.

Frequently asked questions

Official sources

1. alan-ai/alan-sdk-web on GitHub
2. Issues
3. Project website
4. README
5. Releases