useChat

The ChatReturn type below is the canonical state/action contract every AgentsKit UI binding adapts. It wraps createChatController from @agentskit/core with the idioms of your host framework (React hook, Vue composable, Svelte store, Solid signal, Angular service, React Native hook, Ink hook). The returned object is not structurally identical in every host: for example, Svelte exposes a Readable<ChatState> plus methods and Vue returns a reactive object.

#Contract

type ChatReturn = {
  messages: Message[]
  status: 'idle' | 'streaming' | 'complete' | 'error'
  input: string
  usage: TokenUsage
  error: Error | null
  send: (text: string) => Promise<void>
  retry: () => Promise<void>
  stop: () => void
  clear: () => Promise<void>
  approve: (toolCallId: string) => Promise<void>
  deny: (toolCallId: string, reason?: string) => Promise<void>
  edit: (messageId: string, text: string, opts?: EditOptions) => Promise<void>
  regenerate: (messageId?: string) => Promise<void>
  setInput: (value: string) => void
  proposeToolCall: (proposal: Pick<ToolCall, 'id' | 'name' | 'args'>) => Promise<ToolCall>
}

#Inputs

type ChatConfig = {
  adapter: AdapterFactory
  tools?: ToolDefinition[]
  skills?: SkillDefinition[]
  memory?: ChatMemory
  retriever?: Retriever
  systemPrompt?: string
  onError?: (e: Error) => void
  onMessage?: (message: Message) => void
}

#Cancellation

stop() aborts the active source, returns the controller to idle, and settles every active assistant message as complete. Late stream and tool updates from the stopped turn are ignored, and memory receives the settled snapshot instead of a stale streaming message. Calling stop() again is safe and has no additional effect.

#Per-framework usage

#Events and observers

Use onMessage for per-message updates or observers for the shared AgentEvent stream. The controller does not expose an onEvent option on ChatConfig; framework bindings mirror the same core contract.

Full schema: Concepts → mental model.

#Related

• Components: ChatContainer · Message · InputBar · ToolCallView · ThinkingIndicator
• Data attributes · Theming
• For agents → React