Chat inside your own app

You will register your app with Hubzoid, give each signed-in person a short pass from your app's server and add a chat to your page that you design yourself. People chat as themselves, signed in by your app, and the agent's tools can reach your app with that person's own access. Your app's API does not change.

Hubzoid speaks AG-UI (opens in a new tab) at /api/agui, so you can build the chat with assistant-ui (opens in a new tab) or CopilotKit (opens in a new tab) using their own packages. Hubzoid ships no client or server library for this. The snippets below and a working example are all you need.

What you needCopy Anchor Link

• A Hub that your app's page can reach, such as https://hub.example.com. The examples use the starter Hub my-hub, so the agent is my-hub.
• Your app's web address, here https://backoffice.example.com, a fictional back office for Kestrel & Oak.
• A server route behind your app's own sign-in that can sign a JWT with any JWT library. If your app already signs people in with JWTs, see your app's own JWTs instead.
• A React page for assistant-ui, or a Node server for the CopilotKit runtime.

hubzoid embed secret backoffice --hub ./my-hub \
  --origin https://backoffice.example.com --agent my-hub \
  --tool app_lookup --tool read_knowledge --token-to app_lookup

Client id: backoffice
Client secret (shown once):
<the secret>

1. Add this under apps: in hubzoid.yaml (the agents pick it up within seconds):

  backoffice:
    secret_ref: secret:deployment/app-backoffice
    origins: ["https://backoffice.example.com"]
    access:
      agents: ["my-hub"]
      tools: [app_lookup, read_knowledge]
    token_to: [app_lookup]

2. Give the app's server these settings:

HUBZOID_URL=https://<your Hubzoid address>
HUBZOID_CLIENT_ID=backoffice
HUBZOID_CLIENT_SECRET=<the secret above>

3. Check it: hubzoid embed list. The rest is in docs/embedding.md.

apps:
  backoffice:                                # the client id
    name: Kestrel & Oak back office
    secret_ref: secret:deployment/app-backoffice
    origins: ["https://backoffice.example.com"]   # pages that may call Hubzoid
    access:                                  # the most this app may allow
      agents: ["my-hub"]
      tools: [app_lookup, read_knowledge]
    token_to: [app_lookup]                   # tools that receive the person's app token
    max_lifetime: 3600                       # longest a pass may last, in seconds

hubzoid embed list --hub ./my-hub

import { SignJWT } from "jose";
const secret = new TextEncoder().encode(process.env.HUBZOID_CLIENT_SECRET);

app.get("/hubzoid/pass", requireSignIn, async (req, res) => {
  const pass = await new SignJWT({
    name: req.user.name,
    access: { agent: "my-hub", tools: ["app_lookup", "read_knowledge"] }, // optional, narrower than the app's limit
    app_token: req.user.apiToken,            // the person's own token for your API (optional)
  })
    .setProtectedHeader({ alg: "HS256" })
    .setIssuer("backoffice")                 // the client id
    .setAudience("hubzoid")
    .setSubject(req.user.id)                 // your app's user id
    .setIssuedAt()
    .setExpirationTime("10m")
    .sign(secret);
  res.type("text").send(pass);
});

PASS=$(hubzoid embed pass backoffice priya --hub ./my-hub)
curl -N https://hub.example.com/api/agui \
  -H "Authorization: Bearer $PASS" \
  -H "Content-Type: application/json" \
  -d '{"threadId": "t1", "messages": [{"id": "m1", "role": "user", "content": "When is support open?"}]}'

npm install @assistant-ui/react @assistant-ui/react-ag-ui @ag-ui/client

import { useMemo } from "react";
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { HttpAgent } from "@ag-ui/client";
import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";

const HUBZOID = "https://hub.example.com";   // the agent's address

async function withPass(url, init = {}) {
  const pass = await (await fetch("/hubzoid/pass")).text();
  return fetch(url, { ...init, credentials: "omit",
                      headers: { ...init.headers, Authorization: `Bearer ${pass}` } });
}

export function Chat({ threadId }) {
  const agent = useMemo(() => new HttpAgent({ url: `${HUBZOID}/api/agui`, threadId, fetch: withPass }), [threadId]);
  const runtime = useAgUiRuntime({ agent, resumeTranscript: "appended" });
  return <AssistantRuntimeProvider runtime={runtime}>{/* your chat UI */}</AssistantRuntimeProvider>;
}

import httpx
from agents import function_tool
from hubzoid.embed import app_token


@function_tool
def app_lookup(query: str) -> str:
    """Look up orders in the back office for the signed-in person."""
    token = app_token()  # None unless this tool is in token_to and the reply came from your app
    r = httpx.get("https://backoffice.example.com/api/orders",
                  params={"q": query}, headers={"Authorization": f"Bearer {token}"})
    return r.text

Approvals and questionsCopy Anchor Link

When a tool needs a person's approval, or the agent asks a question, the run ends with an AG-UI interrupt: RUN_FINISHED with outcome: {type: "interrupt", interrupts: [...]}. Your page answers with a new run whose resume lists the answers, and the reply continues in that response.

Your app's own JWTsCopy Anchor Link

If your app already signs people in with JWTs (Auth0, Clerk, Keycloak, Okta or your own), Hubzoid can check them directly. You need no secret and no pass route:

apps:
  portal:
    mode: jwt
    issuer: https://kestrel-oak.eu.auth0.com/
    audience: https://hub.example.com
    jwks_url: https://kestrel-oak.eu.auth0.com/.well-known/jwks.json   # or public_key, or secret_ref
    origins: ["https://portal.example.com"]
    access: {agents: ["my-hub"], tools: [read_knowledge, app_lookup]}
    scopes:                                  # how access is decided
      claim: scope
      map:
        "chat:my-hub": {agents: ["my-hub"], tools: [read_knowledge, app_lookup]}
    # or, instead of scopes:  all_users: true
    token_to: [app_lookup]                   # these tools receive the person's JWT itself

A token without a mapped scope gets no access.

OptionsCopy Anchor Link

The app entryCopy Anchor Link

Each app under apps: sets its origins, its secret and the most it may allow.

What a pass may sayCopy Anchor Link

A pass needs iss, aud, sub, iat and exp. It may also carry labels, a narrower access and the person's app_token.

A pass is signed, not encrypted, so the browser can read it. Put in app_token only a token the browser may see, or mint a narrow, short-lived one for it.

Page contextCopy Anchor Link

Send what the person is looking at with each message as forwardedProps: { hubzoid: { page: { doctype: "Sales Order", name: "SO-1001" } } }, or as AG-UI context. The agent receives it as labelled data, never as instructions, at most 4,000 characters, and it never changes access.

EndpointsCopy Anchor Link

All take Authorization: Bearer <pass or app JWT>. Behind a gateway, put the agent's address (/b/<agent>) in front.

Security and limitsCopy Anchor Link

• Your app vouches for the person. Keep the client secret on your server. The browser only ever sees short passes.
• Only the app's origins may call from a browser, without credentials. A request whose Origin is not the app's is refused. These routes never read a Hubzoid cookie, and a request with both a cookie and a pass is refused.

What it does not doCopy Anchor Link

• No Hubzoid account is created for people who come from your app. Their chats are kept under a private id made from your app and their user id, which never matches a Hubzoid account or anyone's grants. Name and email are labels only.
• Hubzoid ships no client or server package for this. You use the AG-UI, assistant-ui or CopilotKit packages.
• Messages are text only, and tools your page declares in AG-UI are ignored.
• A reply cut off by a Hubzoid restart does not carry on by itself. It continues when the person is back with a fresh pass.

If something goes wrongCopy Anchor Link

A refused request answers with {"detail": {"code", "message"}}. Show the message to the person.

The working exampleCopy Anchor Link

The Hubzoid repository has a complete stand-in company app in examples/embed-agui (opens in a new tab). Its README has the commands to run it.

Next stepsCopy Anchor Link