# `useAssistant()`

Allows you to handle the client state when interacting with an OpenAI compatible assistant API.
This hook is useful when you want to integrate assistant capabilities into your application,
with the UI updated automatically as the assistant is streaming its execution.

This works in conjunction with [`AssistantResponse`](./assistant-response) in the backend.

## Import

<Tabs items={['React', 'Svelte']}>
  <Tab>
    <Snippet
      text="import { useAssistant } from '@ai-sdk/react'"
      dark
      prompt={false}
    />
  </Tab>
  <Tab>
    <Snippet
      text="import { useAssistant } from '@ai-sdk/svelte'"
      dark
      prompt={false}
    />
  </Tab>
</Tabs>

## API Signature

### Parameters

<PropertiesTable
  content={[
    {
      name: 'api',
      type: 'string',
      description:
        'The API endpoint that accepts a threadId and message object and returns an AssistantResponse stream. It can be a relative path (starting with `/`) or an absolute URL.',
    },
    {
      name: 'threadId',
      type: 'string | undefined',
      isOptional: true,
      description:
        'Represents the ID of an existing thread. If not provided, a new thread will be created.',
    },
    {
      name: 'credentials',
      type: "'omit' | 'same-origin' | 'include' = 'same-origin'",
      isOptional: true,
      description: 'Sets the mode of credentials to be used on the request.',
    },
    {
      name: 'headers',
      type: 'Record<string, string> | Headers',
      isOptional: true,
      description: 'Headers to be passed to the API endpoint.',
    },
    {
      name: 'body',
      type: 'any',
      isOptional: true,
      description: 'Additional body to be passed to the API endpoint.',
    },
    {
      name: 'onError',
      type: '(error: Error) => void',
      isOptional: true,
      description:
        'Callback that will be called when the assistant encounters an error',
    },
    {
      name: 'fetch',
      type: 'FetchFunction',
      isOptional: true,
      description:
        'Optional. A custom fetch function to be used for the API call. Defaults to the global fetch function.',
    },
  ]}
/>

### Returns

<PropertiesTable
  content={[
    {
      name: 'messages',
      type: 'Message[]',
      description: 'The current array of chat messages.',
    },
    {
      name: 'setMessages',
      type: 'React.Dispatch<React.SetStateAction<Message>>',
      description: 'Function to update the `messages` array.',
    },
    {
      name: 'threadId',
      type: 'string | undefined',
      description: 'The current thread ID.',
    },
    {
      name: 'setThreadId',
      type: '(threadId: string | undefined) => void',
      description:
        "Set the current thread ID. Specifying a thread ID will switch to that thread, if it exists. If set to 'undefined', a new thread will be created. For both cases, `threadId` will be updated with the new value and `messages` will be cleared.",
    },
    {
      name: 'input',
      type: 'string',
      description: 'The current value of the input field.',
    },
    {
      name: 'setInput',
      type: 'React.Dispatch<React.SetStateAction<string>>',
      description: 'Function to update the `input` value.',
    },
    {
      name: 'handleInputChange',
      type: '(event: any) => void',
      description:
        "Handler for the `onChange` event of the input field to control the input's value.",
    },
    {
      name: 'submitMessage',
      type: '(event?: { preventDefault?: () => void }) => void',
      description:
        'Form submission handler that automatically resets the input field and appends a user message.',
    },
    {
      name: 'status',
      type: "'awaiting_message' | 'in_progress'",
      description:
        'The current status of the assistant. This can be used to show a loading indicator.',
    },
    {
      name: 'append',
      type: '(message: Message | CreateMessage, chatRequestOptions: { options: { headers, body } }) => Promise<string | undefined>',
      description:
        "Function to append a user message to the current thread. This triggers the API call to fetch the assistant's response.",
    },
    {
      name: 'stop',
      type: '() => void',
      description:
        'Function to abort the current request from streaming the assistant response. Note that the run will still be in progress.',
    },
    {
      name: 'error',
      type: 'undefined | Error',
      description:
        'The error thrown during the assistant message processing, if any.',
    },
  ]}
/>


## Navigation

- [useChat](/v4/docs/reference/ai-sdk-ui/use-chat)
- [useCompletion](/v4/docs/reference/ai-sdk-ui/use-completion)
- [useObject](/v4/docs/reference/ai-sdk-ui/use-object)
- [useAssistant](/v4/docs/reference/ai-sdk-ui/use-assistant)
- [AssistantResponse](/v4/docs/reference/ai-sdk-ui/assistant-response)
- [convertToCoreMessages](/v4/docs/reference/ai-sdk-ui/convert-to-core-messages)
- [appendResponseMessages](/v4/docs/reference/ai-sdk-ui/append-response-messages)
- [appendClientMessage](/v4/docs/reference/ai-sdk-ui/append-client-message)
- [createDataStream](/v4/docs/reference/ai-sdk-ui/create-data-stream)
- [createDataStreamResponse](/v4/docs/reference/ai-sdk-ui/create-data-stream-response)
- [pipeDataStreamToResponse](/v4/docs/reference/ai-sdk-ui/pipe-data-stream-to-response)
- [StreamData](/v4/docs/reference/ai-sdk-ui/stream-data)


[Full Sitemap](/sitemap.md)