Persona.js - Add WebMCP-native AI chat to any Frontend

@blah_mad sounds like you've built something real before :)

So while Persona does have built-in event debugging in the UI you can optionally turn on (screenshots attached), there is also a deeper set of JS events you can listen to for messages, results, approvals etc in a lot more detail: https://github.com/runtypelabs/persona/blob/main/packages/widget/docs/PROGRAMMATIC-CONTROL.md?plain=1#L562

The messages in particular seem to be right up your alley for the deep debugging use case:

type AgentWidgetMessage = {
  id: string;                    // Unique message identifier
  role: "user" | "assistant" | "system";
  content: string;               // Message text content
  createdAt: string;             // ISO timestamp
  streaming?: boolean;           // Whether message is still streaming
  variant?: "assistant" | "reasoning" | "tool";
  sequence?: number;             // Message ordering
  reasoning?: AgentWidgetReasoning;
  toolCall?: AgentWidgetToolCall;
  tools?: AgentWidgetToolCall[];
  viaVoice?: boolean;            // Indicates if user message was sent via voice input
};

You'd get that info by hooking into Persona init and watching for the assistant messages:

window.addEventListener('persona:chat-ready', (e) => {
  const handle = e.detail;
  handle.on('assistant:message', (msg) => console.log(msg));
  handle.open();
});

// or

const chat = initAgentWidget({
  target: 'body',
  config: { apiUrl: '/api/chat/dispatch' }
});

chat.on('assistant:message', (message) => {
  console.log('Assistant message sent:', message.content);
  if (message.viaVoice) {
    console.log('Message was sent via voice recognition');
  }
});

@odeth_negapatan1 thanks! And yeah, we have tested on WordPress and Shopify. Persona drops in great there because you can use the script tag (CDN) deployment which doesn’t need a build step. All the init and theme configuration can be set in script tag data params.

We spent a lot of time determining the right loading methods for each type of site. Getting the different methods working in the same library while keeping the bundle size tiny, without regressions in functionality, was not easy.

@erik_christensen really appreciate your real-world validation, it was great to see how cleanly Persona's capabilities mapped to the needs of your team. I think you'll be a great real-world success story very soon as you get to production with it - can't wait to see what you build.

@erik_christensen exactly. I love the emergent benefit you get from thinking about the frontend as a source of tools. Many times the logic you already built there is 1:1 with what you’d want an agent to perform.

@tang_weigang some of what you are talking about is backend related, so it's up to the AI framework or platform you use.

The actual SSE spec Person is using has an "await" event that can be implemented which includes information on the reason (LLM generated) and user decision (approve, always approve, deny, timeout). The UI automatically shows when using that event and is extendable with your own approval UX.

On the WebMCP front, you are in control over what is registered on the front end, which usually means you have already built something to respect permissions (say, if the session is trying to be hijacked with a link, you'd verify the request on the backend powering the JS function registered for WebMCP)

Runtype is the reference implementation of the SSE spec and includes more control on the backend for which tools are approved both at the model level and WebMCP tool level (so, you can have registered tools that are "blocked" for a certain agent). The SSE events are enriched with provenance as well, so you can track the whole chain.

In the repo the most thorough example beyond that is the AI SDK WebMCP example, which includes a supporting doc detailing a lot of what I'm talking about here for those building in another stack: https://github.com/runtypelabs/persona/blob/main/docs/webmcp-without-runtype.md

@thenameisarian thanks! In terms of discovery, the WebMCP register tool methods that Persona looks for are the same ones other agents that interact with the front end would read from in the future. So the standard helps there.

We also have built into A2A and MCP as standards on the server side at Runtype to help other agents hook into what is powering Persona too.

@jn263 thanks! The token limits could technically be set up by listening events Persona fires and preventing messages from being sent in a session past a certain amount.

That of course would need to be enforced in the backend as well if you wanted to really prevent it!

@dipankar_sarkar for WebMCP the default is Persona reads the active tools so you’ll get the active state of the app if, however you can override that functionality. On the Runtype side we have more server tooling to lock down tools, implement guardrails, and log requests that we found the FE alone couldn’t do.

Persona in a way just accelerates you to the point you know more about what your server needs to do, to get the right blend of UX and security.

@petrkovacik Thanks! The team leading the standards effort is really cool as well.

@dipankar_sarkar within a run, the model plans against a snapshot taken at dispatch, so there's no mid-run "tool vanished" notification, but if a tool unregisters before execution, the bridge re-reads the live registry and returns a structured isError result like:

{ isError: true, content: [{ type: "text", text: "WebMCP tool not registered on this page: <name>" }] }

Then the model can re-plan on in the same run without aborting.

Every client-side failure mode (unregistered, allowlist-excluded, user-declined, timeout) resolves this way, and the next turn re-snapshots the registry so the advertised toolset re-converges with app state within one turn.

@thamibenjelloun Yep, you have control over the tools registered on the FE and the "await" SSE event handles the user confirmation UX. That last piece is automatically handled in two scenarios within Persona: when you use Runtype and the AI SDK example. However the spec is reasonable easy to add to any AI framework or platform with approvals.