Use the hosted runtime

useAssistedRuntime connects the panel to a Super Assist project with its publishable key. The tutorial sets up a project and mounts the panel. This page covers the hook’s other options. The reference lists them all.

const runtime = useAssistedRuntime({ key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY! });

Answer with another agent

The project’s default agent answers unless you pass agent, the id of another agent of your organization. The id is on the agent’s page in the dashboard, behind the copy button beside its name:

const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  agent: process.env.NEXT_PUBLIC_SUPER_ASSIST_AGENT,
});

Each agent keeps its own threads for each end user, so another agent starts with another thread list.

Name the signed-in user

Pass the signed-in user, and their threads follow them across browsers. Super Assist takes the id as you give it and records it as unverified, so use an id that is stable and not guessable by other users:

const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  user: session ? { id: session.user.id, name: session.user.name } : undefined,
});

Without a user, the browser is a visitor. The hook keeps a random id in localStorage, one per publishable key, and the visitor’s threads stay with that browser until its storage is cleared. A visitor’s threads are never merged into a user’s when they sign in.

Point at another Super Assist origin

host is the Super Assist origin, https://superassist.app by default. Set it when your app talks to another one, such as Super Assist’s own development server on http://localhost:4310. An unset variable falls back to the default:

const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  host: process.env.NEXT_PUBLIC_SUPER_ASSIST_HOST,
});

Point at a route of your own

Super Assist’s dashboard chats with an agent over a route its session cookie authenticates, with no publishable key. basePath points the runtime at such a route on the page’s own origin: the thread list opens on basePath, and each thread on basePath/:id, both the Cloudflare Agents sockets the hosted route serves. Pass a key or a basePath, not both:

const runtime = useAssistedRuntime({ basePath: `api/v1/agents/${agent.id}/threads` });

Keep the open thread in the URL

The hook picks a thread on its own: the one you pass as thread, else the most recent, and a new one when there are none. onThreadChange reports every pick, so a page can keep the open thread in its URL and open the same thread after a reload:

const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  thread: searchParams.get("thread") ?? undefined,
  onThreadChange: (id) => router.replace(`?thread=${id}`),
});

Handle a refused connection

Super Assist checks the key, the page’s origin, the agent and the end user before it opens anything. A refused connection closes with a code, and the hook does not retry it:

Code	Why	Fix
4401	The publishable key is unknown, or it was rolled.	Use the project’s current key.
4403	The page’s origin is not one of the project’s allowed origins.	Add the origin under Allowed origins on the project’s page.
4404	The project has no default agent, or agent names no agent of the organization.	Pick the project’s Default agent, or pass an agent’s id.
4400	Neither a user nor a visitor id was sent.	Pass a user with an id, or leave user out for a visitor.

A new project allows http://localhost:3000 and http://localhost:5173, so add your production origin before you deploy. Open the project in the dashboard, enter the origin under Allowed origins, and press Add. The API sets allowedOrigins and defaultAgentId too, with PATCH /api/v1/projects/{id}.

An allowed origin is a scheme, host and optional port, such as https://shop.example.com, or https://*.example.com for every subdomain.

onConnectionError gets the error with the code in error.code and the reason in error.reason. It logs to the console by default. To show it, keep it in state:

const [refused, setRefused] = useState<string>();
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  onConnectionError: (error) => setRefused(error.reason),
});