Deploy Your Agent

Choose where users meet your agent and who may start sessions — widget, SDKs, or phone; public or authenticated

Your agent is one artifact with many front doors. Deploying it is two independent decisions:

1. Where users meet your agent — a prebuilt widget, your own UI built on the SDKs, a phone number, or a custom client.
2. Who may start sessions — anyone visiting your pages, or only clients your backend has vouched for.

Every surface runs the same agent with the same published configuration, and the browser surfaces work with either access mode.

Publishing gates every channel: sessions always run the agent’s published configuration, and creating a session against an agent that has never been published fails. Publish before wiring up any channel.

Where users meet your agent

In increasing order of integration effort:

Widget

Drop a prebuilt call widget into your site — two lines of HTML, zero build step.

Your own UI

Build a custom experience with the Web SDK or React SDK — events, transcripts, audio controls.

Phone

Bind a number and callers dial straight in — no client code at all.

Custom client

On a stack the SDKs don’t cover, implement the wire protocol directly.

Who may start sessions

The widget and the SDKs each work with either access mode — pick per agent. Phone numbers skip this decision entirely: inbound calls connect through telephony, not a browser session.

Public agents

The client connects with just an agentId — no backend, gated by an origin allowlist and rate limits.

Authenticated sessions

Your backend creates a short-lived session token with your API key — trusted attribution and full control.

	Public agent ID	Session token
Credential in browser	None	Short-lived session token
Requires	Agent set to public + allowed origins	Your own backend endpoint
Session parameters set by	The SDK (overrides, dynamicVariables, language, toolEvents options)	Your backend, in the creation request
Best for	Demos, marketing pages, low-friction embeds	Production apps with signed-in users

Still deciding?

You are building	Start with
A call button on an existing site, no build step	Widget with public access
A demo or marketing page without a backend	Web SDK on a public agent
Voice calls inside a web app with signed-in users	Web SDK with authenticated sessions
A React or Next.js frontend	React SDK
A phone line callers dial in to	Phone numbers and transfers
Server-side session creation and history retrieval	Authenticated sessions and conversation history
A client on a stack the SDKs don’t cover	Wire protocol

How a browser session starts

For private agents, your backend creates the session — your API key never ships to the browser. The browser SDK takes the resulting session token and handles audio and transport from there.

Your backend

curl --request POST https://api.fish.audio/v1/agent/sessions \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "agent_id": "YOUR_AGENT_ID" }'
# → 201 session token — return it to your frontend as-is

Your frontend

import { AgentSession } from "@fishaudio/agent-client";

// sessionToken = the create-session response, passed through unchanged
const session = await AgentSession.start({ sessionToken });

Agents marked public skip the backend step entirely — the SDK connects with just an agentId, gated by an origin allowlist and rate limits.

For phone calls there is no client integration: assign a number, and inbound calls connect directly to your agent — which can transfer callers to another number mid-call. See Phone numbers.

Going further

Versions & publishing

The publish step every channel depends on.

Authenticated sessions

The full session-creation reference — request fields, token lifetime, errors.

Conversation history

List sessions and read full transcripts over REST.

Wire protocol

The wire-level session contract, for building your own client.