Appearance
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
messagesor 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.
submittedcovers waiting for the first text, local tool execution, and waiting for the model's next reply after a tool result.streamingbegins when text arrives.AIChat.Conversationautomatically shows a waiting indicator whilesubmitted.
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:
truewhen the request completes successfully,falsewhen 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 activetoolCalls, and ignores late events from the stopped request