Skip to content
View as Markdown

useAIChat ​

React hook for AI Gateway chat on top of createAIGatewayClient, with optional local tool support.

Signature ​

typescript
const useAIChat: (config: {
  client: AIGatewayClient;
  model: string;
  tools?: Record<string, AILocalTool>;
}) => {
  messages: AIChatMessage[];
  toolCalls: { id: string; name: string }[];
  status: "ready" | "submitted" | "streaming" | "error";
  error?: Error;
  sendMessage: (message: string) => Promise<boolean>;
  stop: () => void;
};

Return Value ​

messages ​

typescript
interface AIChatMessage {
  id: string;
  role: "user" | "assistant";
  content: string;
}

toolCalls ​

  • Type: { id: string; name: string }[]
  • Description: Tool calls requested by the model in the active flow, including earlier tool rounds of the current request. This transient list is cleared when the response finishes, is stopped, or fails; it is never added to messages or conversation history.

Calls become available before local tool execution. They record requested tool names, not successful execution. Arguments and results remain internal.

status ​

  • Type: "ready" | "submitted" | "streaming" | "error"
  • Description: Current request state. submitted covers waiting for the first text, local tool execution, and waiting for the model's next reply after a tool result. streaming begins when text arrives. AIChat.Conversation automatically shows a waiting indicator while submitted.

error ​

  • Type: Error | undefined
  • Description: Last request error, if any

sendMessage() ​

  • Type: (message: string) => Promise<boolean>
  • Description: Appends a user message and streams the assistant response
  • Returns: true when the request completes successfully, false when the call is ignored, stopped, or fails

stop() ​

  • Type: () => void
  • Description: Aborts the current request if one is in progress

tools ​

Register local tools under a single object using defineAIChatTool(...). Their schemas must implement both Standard Schema validation and Standard JSON Schema generation (for example, Zod 4). Provider-native tools are not supported.

Usage ​

tsx
import {
  createAuthClient,
  createAIGatewayClient,
  defineAIChatTool,
  useAIChat,
} from "@tailor-platform/app-shell";
import { z } from "zod/v4";

const authClient = createAuthClient({
  clientId: "your-client-id",
  appUri: "https://xyz.erp.dev",
});

const aiClient = createAIGatewayClient({
  gatewayUri: "https://your-ai-gateway.example.com",
  authClient,
});

const lookupCustomer = defineAIChatTool({
  description: "Look up a customer in the current workspace",
  schema: z.object({
    customerId: z.string(),
  }),
  async execute({ customerId }) {
    return { customerId, name: "Acme Corp" };
  },
});

export function ChatScreen() {
  const { messages, toolCalls, sendMessage, status, stop, error } = useAIChat({
    client: aiClient,
    model: "gpt-5-mini",
    tools: {
      lookupCustomer,
    },
  });

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role}: {message.content}
        </div>
      ))}
      {toolCalls.map((call) => (
        <div key={call.id}>Tool call: {call.name}</div>
      ))}

      <button
        onClick={() => void sendMessage("Hello")}
        disabled={status === "submitted" || status === "streaming"}
      >
        Send
      </button>
      <button onClick={stop} disabled={status !== "submitted" && status !== "streaming"}>
        Stop
      </button>
      {error ? <div>{error.message}</div> : null}
    </div>
  );
}

Notes ​

  • AppShell chooses the appropriate AI Gateway transport automatically
  • Public messages stay user/assistant text-first; tool calls and results never become conversation messages
  • System prompts and custom history shaping should use the low-level client directly
  • stop() keeps already-streamed assistant text, clears the active toolCalls, and ignores late events from the stopped request