@economic/agents-react

React hooks for connecting to agents built with @economic/agents. They wrap the Cloudflare agents and @cloudflare/ai-chat hooks and add typed connection state, message feedback, and the per-user multi-chat model used by Assistant.

Install

npm install @economic/agents-react

React 19 is a peer dependency.

Which hook do I use?

The package exports three hooks, layered on top of each other:

• useAgent — the thin connection primitive both build on. Reach for it only when you need raw access to the connection.
• useChat — connects directly to a single chat agent by name. Use it when you address one conversation yourself (e.g. one chat per route) rather than going through an Assistant.
• useAssistant — the high-level hook for the v2 model: one assistant per user, many chats. It manages the chat list (create / open / delete), connects to the right chat facet, and exposes the active chat. Use this when your server uses an Assistant.

useAgent

The connection primitive useChat and useAssistant are built on. Connects to an agent by name and exposes its connection and call for invoking @callable methods.

import { useAgent } from "@economic/agents-react";

const agent = useAgent({
  host: "localhost:8787",
  agentName: "SupportAgent",
  name: "support",
  actorId: userId, // when set, the DO name becomes `${actorId}:${name}`
  authToken,
});

await agent.call("checkOrder", ["1234"]);
console.log(agent.state?.status);

useChat

Connects to a single chat agent by name — no Assistant needed. Returns the connection, the message interface, and message-feedback helpers.

import { useChat } from "@economic/agents-react";

const { status, chat, submitMessageFeedback, getMessageFeedback } = useChat({
  host: "localhost:8787",
  agentName: "MyChatAgent",
  name: `${userId}:${chatId}`,
  authToken,
  toolContext: { locale: "en-DK" },
});

// send a message
chat.sendMessage({ role: "user", parts: [{ type: "text", text: "Hello" }] });

// rate a message (1 = up, -1 = down) and read all feedback
await submitMessageFeedback(messageId, 1, "Helpful!");
const feedback = await getMessageFeedback();

Returns

useAssistant

For the per-user, many-chats model: connects to the user's Assistant DO, keeps the chat list in sync, and manages which chat is active.

import { useAssistant } from "@economic/agents-react";

function Chat({ userId, authToken }: { userId: string; authToken: string }) {
  const { status, chats, currentChatName, assistant, chat } = useAssistant({
    host: "localhost:8787",
    agentName: "MyAssistant", // matches the Assistant DO binding/class name
    name: userId, // the Assistant is keyed by user
    authToken,
    toolContext: { locale: "en-DK" }, // forwarded to server tools as the request body
    welcomeMessage: "Hi! How can I help?",
  });

  return (
    <div>
      <button onClick={() => assistant.createChat()}>New chat</button>

      <ul>
        {chats.map((c) => (
          <li key={c.name}>
            <button onClick={() => assistant.openChat(c.name)}>{c.title ?? "Untitled"}</button>
            <button onClick={() => assistant.deleteChat(c.name)}>Delete</button>
          </li>
        ))}
      </ul>

      {chat.chat.messages.map((m) => (
        <Message key={m.id} message={m} />
      ))}

      <Composer
        onSend={(text) =>
          chat.chat.sendMessage({
            role: "user",
            parts: [{ type: "text", text }],
          })
        }
      />
    </div>
  );
}

Returns

assistant actions:

Titles and summaries are generated server-side a few seconds after the first message, so refetch with getChats() shortly after sending the opening message if you want the new title to appear.

The active empty chat is represented locally until its first turn registers it on the server.

After the active draft's first turn finishes, useAssistant refreshes the chat list automatically so the temporary entry is replaced by its persisted title and summary.

Options

All hooks share these connection options (useAssistant omits actorId):

Types

type AgentConnectionStatus =
  | "connecting"
  | "reconnecting"
  | "connected"
  | "disconnected"
  | "unauthorized"
  | "error";
type AgentConnectionType = "agent" | "chat" | "assistant";

type AgentConnectionState = {
  status: AgentConnectionStatus;
  type: AgentConnectionType;
  subAgentName?: string;
};

type ChatSummary = {
  name: string;
  isTemporary?: boolean; // true for the active chat before its first turn is registered
  title?: string;
  summary?: string;
  created_at: number;
  updated_at: number;
};

type MessageFeedback = {
  message_id: string;
  rating: number; // 1 = up, -1 = down
  comment?: string;
  created_at: number;
  updated_at: number;
};

The package also exports the handler types AssistantActions, GetChatsHandler, CreateChatHandler, OpenChatHandler, DeleteChatHandler, MessageFeedbackHandler, and GetMessageFeedbackHandler.

Authentication

Pass a JWT as authToken. It is sent both as an Authorization: Bearer … header and as a WebSocket subprotocol (["bearer", token]), matching the server-side getAuthenticator(env). When verification fails, the connection status becomes "unauthorized".

When the agent refuses a caller with a reason (an AuthenticationError with { reason } on the server), useChat returns it as refusalReason, so a client can tell refusals apart without matching close messages:

const { status, refusalReason } = useChat({/* … */});

if (status === "unauthorized" && refusalReason === "access-denied") {
  // the user has no access: don't retry with a new token
}

With useAssistant, it's chat.refusalReason.

Tool approvals

useChat and useAssistant show a durable tool's step approval (step.requestApproval on the server) exactly as they show a tool's approval: its part has the same state (approval-requested, then approval-responded or output-denied) and approval, and chat.addToolApprovalResponse({ id, approved }) answers both. A client handles them with the same code.

getToolApproval(part) returns the approval with the descriptor the agent sent: the action's approvalSummary or the step's summary as summary, and its risk as risk.

import { getToolApproval, getToolPartState } from "@economic/agents-react";

if (getToolPartState(part) === "waiting-approval") {
  const approval = getToolApproval(part)!;

  // approval.descriptor?.summary, approval.descriptor?.risk ("low" | "medium" | "high")
  chat.addToolApprovalResponse({ id: approval.id, approved: true });
}

A rejected step approval goes back to the tool, which decides what happens next, so the part then shows the tool's result rather than staying denied.