@zaby-ai/aiui-react

React agents, hooks, and UI components for AG-UI-compatible AIUI streams.

Use this package when a tenant application needs to connect to Zaby agent runtime streams from the browser with a disposable runtime token. Token minting stays on your server; the browser only receives a short-lived runtime token and keeps it in memory.

Install

npm install @zaby-ai/aiui-react @zaby-ai/aiui-core

Disposable Token Runtime

ZabyRuntimeAgent is a Zaby disposable-token runtime adapter that consumes AG-UI-compatible streams from Zaby. It is not a replacement for every upstream AG-UI client transport; it focuses on Zaby tenant applications using runtime tokens.

Production contract:

• runtimeToken must call your backend token route, not Zaby tenant APIs directly.
• Store the returned token in memory only. Do not put runtime tokens in localStorage, sessionStorage, cookies, URLs, logs, or analytics events.
• Your backend calls the Zaby provisioning API with a tenant provisioning API key.
• Rotate before expiry by sending the previous token, or by sending uniqueId plus tokenFamilyId from your backend session.
• Never expose tenant API keys, provisioning API keys, Cloudflare secrets, or signing secrets to the browser.

Customer backend route:

import { Zaby } from '@zaby-ai/sdk';

const zaby = new Zaby({ apiKey: process.env.ZABY_PROVISIONING_API_KEY! });

app.post('/api/zaby/runtime-token', requireUser, async (req, res) => {
  const token = await zaby.runtimeTokens.create({
    externalAppId: process.env.ZABY_EXTERNAL_APP_ID!,
    deploymentId: process.env.ZABY_AGENT_DEPLOYMENT_ID!,
    uniqueId: req.user.id,
    externalConversationId: req.body.conversationId,
    quotaPolicyId: req.user.runtimeQuotaPolicyId,
    metadata: { plan: req.user.plan },
  });

  res.json({
    token: token.token,
    expiresAt: token.expiresAt,
    tokenFamilyId: token.tokenFamilyId,
    rotateAfterSeconds: token.rotateAfterSeconds,
  });
});

import { useAgentChat, ZabyRuntimeAgent } from '@zaby-ai/aiui-react';

let runtimeTokenCache: {
  expiresAt: string;
  token: string;
  tokenFamilyId?: string;
} | null = null;

async function getRuntimeToken() {
  if (runtimeTokenCache) {
    const expiresAt = new Date(runtimeTokenCache.expiresAt).getTime();
    if (expiresAt - Date.now() > 120_000) return runtimeTokenCache.token;
  }

  const response = await fetch('/api/zaby/runtime-token', { method: 'POST' });
  if (!response.ok) throw new Error('Unable to mint runtime token');
  runtimeTokenCache = await response.json();
  return runtimeTokenCache.token;
}

const agent = new ZabyRuntimeAgent({
  baseUrl: process.env.NEXT_PUBLIC_ZABY_API_BASE_URL,
  runtimeToken: getRuntimeToken,
  threadId: crypto.randomUUID(),
});

export function AgentChat() {
  const chat = useAgentChat({ agent });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const form = new FormData(event.currentTarget);
        void chat.sendMessage(String(form.get('message') ?? ''));
        event.currentTarget.reset();
      }}
    >
      <ol>
        {chat.messages.map((message) => (
          <li key={message.id}>{message.content}</li>
        ))}
      </ol>
      <input name="message" />
      <button type="submit" disabled={chat.isLoading}>Send</button>
    </form>
  );
}

ZabyRuntimeAgent performs two browser-safe requests:

1. POST /api/v1/agent-runtime/runs with Authorization: Bearer <runtime-token>
2. GET /api/v1/agent-runtime/runs/{runId}/aiui with Accept: text/event-stream

The default API origin is https://genapi.zaby.io. Pass baseUrl when your tenant deployment uses a different configured gateway.

Custom Run Payloads

By default, the agent sends the latest user message plus full AG-UI run context:

new ZabyRuntimeAgent({
  runtimeToken,
  createRunPayload: (input) => ({
    input: {
      message: input.messages.at(-1)?.content,
      messages: input.messages,
      state: input.state,
      tools: input.tools,
      context: input.context,
      forwardedProps: input.forwardedProps,
    },
    metadata: { source: 'tenant-app' },
  }),
});

Exports

• ZabyRuntimeAgent for disposable-token Zaby runtime streams
• HttpAgent for direct AG-UI-compatible HTTP/SSE endpoints
• useAgentChat for React chat state, streaming messages, tools, UI blocks, activities, and state deltas
• applyStateDelta for JSON Patch state updates
• Chat UI components: Chat, InputArea, MessageList, and AiuiBlockRenderer

Scripts

npm test
npm run lint
npm run build

License

MIT