@fishaudio/agent-widget

Embeddable <fish-agent> voice-agent widget for Fish Audio agents. A floating launcher expands into a voice-first chat card with live transcript, text input, client-tool chips, and a consent gate. It is a custom element rendering into shadow DOM, built on @fishaudio/agent-client.

Just want a script tag? @fishaudio/agent-widget-embed is the same widget pre-bundled as one CDN file that registers <fish-agent> on load. No install, no build step:

<fish-agent agent-id="your-agent-id"></fish-agent>
<script src="https://unpkg.com/@fishaudio/agent-widget-embed" async type="text/javascript"></script>

Installation

npm install @fishaudio/agent-widget

Quickstart

Importing the package has no side effects. Call registerWidget() once to define the element, then drop the tag anywhere:

import { registerWidget } from "@fishaudio/agent-widget";
registerWidget(); // defines <fish-agent>

<fish-agent agent-id="your-agent-id"></fish-agent>

Exactly one of agent-id or token-endpoint is required. agent-id is for a public agent with your origin allowlisted. token-endpoint is for a private agent. It is a URL on your backend that returns the session-token JSON. Everything else is attributes: agent-name, greeting, proactive-message, proactive-delay, position, the transcript, text-input, mic-muting, and consent switches, language, user-id, dynamic-variables as JSON, and text-contents as JSON overriding any UI string. See the attribute reference. Theme it with CSS custom properties such as --fish-accent on the element.

The element emits bubbling, composed CustomEvents. fish-agent:call carries mutable { options }, so inject clientTools there. fish-agent:connect carries { sessionId }, fish-agent:disconnect carries { reason }, and fish-agent:error carries { code, message }. Dispatch fish-agent:expand on the element or document to open the panel programmatically.

React

@fishaudio/agent-widget/react exports a real <FishAgentWidget> component. It registers and renders the element, takes camelCase props, serializes object props, and surfaces the page events as callback props. clientTools is just a prop. Importing the entry also types the raw <fish-agent> tag in JSX. Requires React 18+ as an optional peer dependency.

import { FishAgentWidget } from "@fishaudio/agent-widget/react";

<FishAgentWidget
  agentId="your-agent-id"
  clientTools={{ highlight_product: ({ productId }) => scrollToProduct(productId) }}
  onConnect={({ sessionId }) => console.log(sessionId)}
/>;

Documentation

• Widget covers behavior, attributes, theming, page events, and private agents.
• Public agents and authenticated sessions compare a public agent id with server-created session tokens.
• Client tools lets the agent call functions in the browser.

License

MIT. Icon path data comes from lucide under ISC. See THIRD-PARTY-NOTICES.txt, also shipped in this npm package.