diff --git a/.changeset/gentle-poets-check.md b/.changeset/gentle-poets-check.md new file mode 100644 index 000000000000..e2b6c4175f9a --- /dev/null +++ b/.changeset/gentle-poets-check.md @@ -0,0 +1,5 @@ +--- +'ai': patch +--- + +Remove experimental from useAssistant and AssistantResponse. diff --git a/docs/pages/docs/api-reference/_meta.json b/docs/pages/docs/api-reference/_meta.json index 3920953fc719..f2782994c27a 100644 --- a/docs/pages/docs/api-reference/_meta.json +++ b/docs/pages/docs/api-reference/_meta.json @@ -1,7 +1,7 @@ { "generative-ui": "Generative UI", "providers": "Providers", - "use-assistant": "experimental_useAssistant", + "use-assistant": "useAssistant", "use-chat": "useChat", "use-completion": "useCompletion", "ai-stream": "AIStream", diff --git a/docs/pages/docs/api-reference/providers/_meta.json b/docs/pages/docs/api-reference/providers/_meta.json index 870b2ea519e5..54b7942255fb 100644 --- a/docs/pages/docs/api-reference/providers/_meta.json +++ b/docs/pages/docs/api-reference/providers/_meta.json @@ -9,5 +9,5 @@ "mistral-stream": "MistralStream", "replicate-stream": "ReplicateStream", "inkeep-stream": "InkeepStream", - "assistant-response": "experimental_AssistantResponse" + "assistant-response": "AssistantResponse" } diff --git a/docs/pages/docs/api-reference/providers/assistant-response.mdx b/docs/pages/docs/api-reference/providers/assistant-response.mdx index 7e2fc7e4e8b1..71f05f18443b 100644 --- a/docs/pages/docs/api-reference/providers/assistant-response.mdx +++ b/docs/pages/docs/api-reference/providers/assistant-response.mdx @@ -1,30 +1,25 @@ --- -title: experimental_AssistantResponse +title: AssistantResponse layout: toc: false --- import { Callout } from 'nextra-theme-docs'; -# `experimental_AssistantResponse` +# `AssistantResponse` -The `experimental_AssistantResponse` class allows you to send a stream of assistant update to `experimental_useAssistant`. +The `AssistantResponse` allows you to send a stream of assistant update to `useAssistant`. - - The `experimental_` prefix indicates that the API is not yet stable and may - change in the future without a major version bump. - +## `AssistantResponse(settings: AssistantResponseSettings, process: AssistantResponseCallback): Response` [#assistantresponse] -## `experimental_AssistantResponse(settings: AssistantResponseSettings, process: AssistantResponseCallback): Response` [#assistantresponse] - -The `experimental_AssistantResponse` class is designed to facilitate streaming assistant responses to the `useAssistant` hook. +The `AssistantResponse` is designed to facilitate streaming assistant responses to the `useAssistant` hook. It receives an assistant thread and a current message, and can send messages and data messages to the client. ## Parameters ### `settings: {threadId: string, messageId: string}` -You can pass the thread and the latest message into the `experimental_AssistantResponse`. This establishes the context for the response. +You can pass the thread and the latest message into the `AssistantResponse`. This establishes the context for the response. - `threadId: string`: The thread ID that the response is associated with. - `messageId: string`: The ID of the latest message that the response is associated with. @@ -42,13 +37,13 @@ It gets invoked with the following functions that you can use to send messages a ### Server-Side Implementation -This example highlights the usage of `experimental_AssistantResponse` +This example highlights the usage of `AssistantResponse` for an OpenAI assistant within a Next.js environment. Server: ```tsx filename="app/api/assistant/route.ts" -import { experimental_AssistantResponse } from 'ai'; +import { AssistantResponse } from 'ai'; import OpenAI from 'openai'; // Create an OpenAI API client (that's edge friendly!) @@ -83,7 +78,7 @@ export async function POST(req: Request) { content: input.message, }); - return experimental_AssistantResponse( + return AssistantResponse( { threadId, messageId: createdMessage.id }, async ({ forwardStream, sendDataMessage }) => { // Run the assistant on the thread diff --git a/docs/pages/docs/api-reference/use-assistant.mdx b/docs/pages/docs/api-reference/use-assistant.mdx index 3802356bd176..b10b20eb08bc 100644 --- a/docs/pages/docs/api-reference/use-assistant.mdx +++ b/docs/pages/docs/api-reference/use-assistant.mdx @@ -1,13 +1,13 @@ --- -title: experimental_useAssistant +title: useAssistant --- import { OptionTable } from '@/components/table'; import { FrameworkTabs, Tab } from '@/components/framework-tabs'; -# experimental_useAssistant +# useAssistant -## `experimental_useAssistant(options: UseAssistantOptions): UseAssistantHelpers` [#experimental_useAssistant] +## `useAssistant(options: UseAssistantOptions): UseAssistantHelpers` [#useAssistant] `useAssistant` is a utility designed to handle the UI state of interacting with an OpenAI-compatible assistant API. This tool is useful when you need to integrate assistant capabilities into your application, @@ -16,17 +16,13 @@ It works in conjunction with `AssistantResponse` in the backend. -To use `experimental_useAssistant` in React projects, you can import it from the `ai/react` subpath. -Here's an example demonstrating the use of `experimental_useAssistant` in a chat interface: +To use `useAssistant` in React projects, you can import it from the `ai/react` subpath. +Here's an example demonstrating the use of `useAssistant` in a chat interface: ```tsx filename="app/assistant.tsx" 'use client'; -import { - Message, - // import as useAssistant: - experimental_useAssistant as useAssistant, -} from 'ai/react'; +import { Message, useAssistant } from 'ai/react'; const roleToColorMap: Record = { system: 'red', @@ -124,7 +120,7 @@ export default function Chat() { ### `UseAssistantHelpers` -The `experimental_useAssistant` hook returns an object with several helper methods and variables to manage the assistant state in the UI: +The `useAssistant` hook returns an object with several helper methods and variables to manage the assistant state in the UI: { // Run the assistant on the thread diff --git a/examples/next-openai/app/assistant/page.tsx b/examples/next-openai/app/assistant/page.tsx index a583641e2fd2..f722e0c29d45 100644 --- a/examples/next-openai/app/assistant/page.tsx +++ b/examples/next-openai/app/assistant/page.tsx @@ -1,6 +1,6 @@ 'use client'; -import { Message, experimental_useAssistant as useAssistant } from 'ai/react'; +import { Message, useAssistant as useAssistant } from 'ai/react'; import { useEffect, useRef } from 'react'; const roleToColorMap: Record = { @@ -29,7 +29,7 @@ export default function Chat() { return (
{error != null && ( -
+
Error: {(error as any).toString()} @@ -59,7 +59,7 @@ export default function Chat() { ))} {status === 'in_progress' && ( -
+
)}
diff --git a/packages/core/react/use-assistant.ts b/packages/core/react/use-assistant.ts index 53fc220cb283..59f9f96efa7d 100644 --- a/packages/core/react/use-assistant.ts +++ b/packages/core/react/use-assistant.ts @@ -100,7 +100,7 @@ export type UseAssistantOptions = { onError?: (error: Error) => void; }; -export function experimental_useAssistant({ +export function useAssistant({ api, threadId: threadIdParam, credentials, @@ -252,3 +252,8 @@ export function experimental_useAssistant({ error, }; } + +/** +@deprecated Use `useAssistant` instead. + */ +export const experimental_useAssistant = useAssistant; diff --git a/packages/core/streams/assistant-response.ts b/packages/core/streams/assistant-response.ts index e35eb4b32f51..ead8f3a942bd 100644 --- a/packages/core/streams/assistant-response.ts +++ b/packages/core/streams/assistant-response.ts @@ -1,22 +1,59 @@ import { AssistantStream } from 'openai/lib/AssistantStream'; +import { Run } from 'openai/resources/beta/threads/runs/runs'; import { formatStreamPart } from '../shared/stream-parts'; import { AssistantMessage, DataMessage } from '../shared/types'; -import { Run } from 'openai/resources/beta/threads/runs/runs'; +/** +You can pass the thread and the latest message into the `AssistantResponse`. This establishes the context for the response. + */ type AssistantResponseSettings = { + /** +The thread ID that the response is associated with. + */ threadId: string; + + /** +The ID of the latest message that the response is associated with. + */ messageId: string; }; +/** +The process parameter is a callback in which you can run the assistant on threads, and send messages and data messages to the client. + */ type AssistantResponseCallback = (options: { + /** +@deprecated use variable from outer scope instead. + */ threadId: string; + + /** +@deprecated use variable from outer scope instead. + */ messageId: string; + + /** +Forwards an assistant message (non-streaming) to the client. + */ sendMessage: (message: AssistantMessage) => void; + + /** +Send a data message to the client. You can use this to provide information for rendering custom UIs while the assistant is processing the thread. + */ sendDataMessage: (message: DataMessage) => void; + + /** +Forwards the assistant response stream to the client. Returns the `Run` object after it completes, or when it requires an action. + */ forwardStream: (stream: AssistantStream) => Promise; }) => Promise; -export function experimental_AssistantResponse( +/** +The `AssistantResponse` allows you to send a stream of assistant update to `useAssistant`. +It is designed to facilitate streaming assistant responses to the `useAssistant` hook. +It receives an assistant thread and a current message, and can send messages and data messages to the client. + */ +export function AssistantResponse( { threadId, messageId }: AssistantResponseSettings, process: AssistantResponseCallback, ): Response { @@ -120,3 +157,8 @@ export function experimental_AssistantResponse( }, }); } + +/** +@deprecated Use `AssistantResponse` instead. + */ +export const experimental_AssistantResponse = AssistantResponse;