Skip to content

The Open Standard for Generative UI

Message context guide (#119)

Hrijul Bhatnagar0c2a8f14880b
diff --git a/docs/docs/guides/customization/advanced-customization/002-message-context.mdx b/docs/docs/guides/customization/advanced-customization/002-message-context.mdx
new file mode 100644
index 000000000..492d3271b
--- /dev/null
+++ b/docs/docs/guides/customization/advanced-customization/002-message-context.mdx
@@ -0,0 +1,367 @@
+---
+description: Using useMessage to implement forms or modify messages
+---
+
+import { Steps, Step } from "@site/components/Steps/Steps";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Interactive Agent Responses
+
+The best part of being able to use response templates and rendering the agent response as a rich user interface is that it allows for an _interactive_ experience. For example,
+instead of making the user type out long responses, they can conveniently fill out a form or press buttons in the agent response. This can be achieved by utilizing
+[`useMessage`](../../../reference/js/react-core/functions/useMessage.md).
+
+`useMessage` is a hook that allows you to access the [`Message`](../../../reference/js/react-core/type-aliases/Message.md) object in your response template components.
+This is useful if you want to modify or format the message before rendering it, or if you want to implement persistent forms in your response template.
+
+Here's an example demonstrating how to implement a form that collects the user's name and email address, and persist it by storing the values in `message.context`.
+
+<Steps>
+
+<Step title="Create a form component">
+
+First, create a form component that will be used to render the response template to collect the user's name and email address.
+
+<Tabs groupId="frontend-lang">
+
+<TabItem value="ts" label="TypeScript">
+
+```tsx title="Form.tsx"
+import { useState } from "react";
+import { useThreadActions } from "@crayonai/react-core";
+
+export const Form = () => {
+ const { processMessage } = useThreadActions();
+
+ const [name, setName] = useState("");
+ const [email, setEmail] = useState("");
+
+ const handleSubmit: React.FormEventHandler<HTMLFormElement> = async (e) => {
+ e.preventDefault();
+ await processMessage({
+ role: "user",
+ message: `Name: ${name}, Email: ${email}`,
+ type: "prompt",
+ isVisuallyHidden: true, // This will hide the message from the user but still send it to the LLM
+ });
+ };
+
+ return (
+ <form onSubmit={handleSubmit}>
+ <input
+ type="text"
+ value={name}
+ onChange={(e) => setName(e.target.value)}
+ placeholder="Name"
+ />
+ <input
+ type="email"
+ value={email}
+ onChange={(e) => setEmail(e.target.value)}
+ placeholder="Email"
+ />
+ <button type="submit">Submit</button>
+ </form>
+ );
+};
+```
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```jsx title="Form.jsx"
+import { useState } from "react";
+import { useThreadActions } from "@crayonai/react-core";
+
+export const Form = () => {
+ const { processMessage } = useThreadActions();
+
+ const [name, setName] = useState("");
+ const [email, setEmail] = useState("");
+
+ const handleSubmit = async (e) => {
+ e.preventDefault();
+ await processMessage({
+ role: "user",
+ message: `Name: ${name}, Email: ${email}`,
+ type: "prompt",
+ isVisuallyHidden: true, // This will hide the message from the user but still send it to the LLM
+ });
+ };
+
+ return (
+ <form onSubmit={handleSubmit}>
+ <input
+ type="text"
+ value={name}
+ onChange={(e) => setName(e.target.value)}
+ placeholder="Name"
+ />
+ <input
+ type="email"
+ value={email}
+ onChange={(e) => setEmail(e.target.value)}
+ placeholder="Email"
+ />
+ <button type="submit">Submit</button>
+ </form>
+ );
+};
+```
+
+</TabItem>
+
+</Tabs>
+
+</Step>
+
+<Step title="Pass the form as a response template">
+
+```tsx title="App.tsx"
+import { Form } from "./Form";
+
+const App = () => {
+ // ... rest of your code
+
+ return (
+ <CrayonChat
+ processMessage={processMessage}
+ // highlight-next-line
+ responseTemplates={[{ name: "form", component: Form }]}
+ />
+ );
+};
+```
+
+</Step>
+
+<Step title="Update your backend to handle the form response template">
+
+Pass the response template schema to the LLM:
+
+<Tabs groupId="frontend-lang">
+
+<TabItem value="ts" label="TypeScript">
+
+```ts title="route.ts"
+// ... rest of your imports
+import {
+ fromOpenAICompletion,
+ templatesToResponseFormat,
+} from "@crayonai/stream";
+import { z } from "zod";
+
+export async function POST(req: NextRequest) {
+ // ... rest of your code
+ // highlight-start
+ const responseFormat = templatesToResponseFormat({
+ schema: z.object({}),
+ name: "form",
+ description:
+ "Use this template to collect the user's name and email address",
+ });
+ // highlight-end
+
+ // pass the response format to the LLM
+ const llmStream = await client.chat.completions.create({
+ model: "gpt-4o",
+ messages: toOpenAIMessages(
+ messages
+ ) as OpenAI.Chat.ChatCompletionMessageParam[],
+ stream: true,
+ // highlight-next-line
+ response_format: responseFormat,
+ });
+
+ // convert the LLM stream to a Crayon stream
+ const responseStream = fromOpenAICompletion(llmStream);
+ return new Response(responseStream as unknown as ReadableStream<Uint8Array>, {
+ headers: {
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache, no-transform",
+ Connection: "keep-alive",
+ },
+ });
+}
+```
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```js title="route.js"
+// ... rest of your imports
+import {
+ fromOpenAICompletion,
+ templatesToResponseFormat,
+} from "@crayonai/stream";
+import { z } from "zod";
+
+export async function POST(req) {
+ // ... rest of your code
+ // highlight-start
+ const responseFormat = templatesToResponseFormat({
+ schema: z.object({}),
+ name: "form",
+ description:
+ "Use this template to collect the user's name and email address",
+ });
+ // highlight-end
+
+ // pass the response format to the LLM
+ const llmStream = await client.chat.completions.create({
+ model: "gpt-4o",
+ messages: toOpenAIMessages(messages),
+ stream: true,
+ // highlight-next-line
+ response_format: responseFormat,
+ });
+
+ // convert the LLM stream to a Crayon stream
+ const responseStream = fromOpenAICompletion(llmStream);
+ return new Response(responseStream, {
+ headers: {
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache, no-transform",
+ Connection: "keep-alive",
+ },
+ });
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+</Step>
+
+<Step title={<>Use <code>useMessage</code> to persist the form data</>}>
+
+Now the form is functional, but it would be odd if the user filled and submitted the form, but the form appeared empty the next time they reloaded the page. To prefill the
+form with the previously submitted data, you can store the values in the assistant message's `message.context` and retrieve them when loading the response.
+
+This can be done by making the following modifications to the form component:
+
+<Tabs groupId="frontend-lang">
+
+<TabItem value="ts" label="TypeScript">
+
+```tsx title="Form.tsx"
+import { useState } from "react";
+import { useThreadActions, useMessage } from "@crayonai/react-core";
+
+export const Form = () => {
+ // highlight-next-line
+ const { message } = useMessage();
+ const { processMessage, updateMessage } = useThreadActions();
+
+ const [name, setName] = useState<string>(
+ // highlight-next-line
+ (message.context?.[0]?.name as string) ?? "" // prefill if the message metadata contains a name
+ );
+ const [email, setEmail] = useState<string>(
+ // highlight-next-line
+ (message.context?.[0]?.email as string) ?? "" // prefill if the message metadata contains an email
+ );
+
+ const handleSubmit: React.FormEventHandler<HTMLFormElement> = async (e) => {
+ e.preventDefault();
+ await processMessage({
+ role: "user",
+ message: `Name: ${name}, Email: ${email}`,
+ type: "prompt",
+ isVisuallyHidden: true, // This will hide the message from the user but still send it to the LLM
+ });
+
+ // highlight-start
+ message.context = [{ name, email }]; // store the newly submitted data in the message context
+ updateMessage(message, true); // update the assistant message context with the updated values
+ // highlight-end
+ };
+
+ return (
+ <form onSubmit={handleSubmit}>
+ <input
+ type="text"
+ value={name}
+ onChange={(e) => setName(e.target.value)}
+ placeholder="Name"
+ />
+ <input
+ type="email"
+ value={email}
+ onChange={(e) => setEmail(e.target.value)}
+ placeholder="Email"
+ />
+ <button type="submit">Submit</button>
+ </form>
+ );
+};
+```
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```jsx title="Form.jsx"
+import { useState } from "react";
+import { useThreadActions, useMessage } from "@crayonai/react-core";
+
+export const Form = () => {
+ // highlight-next-line
+ const { message } = useMessage();
+ const { processMessage, updateMessage } = useThreadActions();
+
+ const [name, setName] = useState(
+ // highlight-next-line
+ message.context?.[0]?.name ?? "" // prefill if the message metadata contains a name
+ );
+ const [email, setEmail] = useState(
+ // highlight-next-line
+ message.context?.[0]?.email ?? "" // prefill if the message metadata contains an email
+ );
+
+ const handleSubmit = async (e) => {
+ e.preventDefault();
+ await processMessage({
+ role: "user",
+ message: `Name: ${name}, Email: ${email}`,
+ type: "prompt",
+ isVisuallyHidden: true, // This will hide the message from the user but still send it to the LLM
+ });
+
+ // highlight-start
+ message.context = [{ name, email }]; // store the newly submitted data in the message context
+ updateMessage(message, true); // update the assistant message context with the updated values
+ // highlight-end
+ };
+
+ return (
+ <form onSubmit={handleSubmit}>
+ <input
+ type="text"
+ value={name}
+ onChange={(e) => setName(e.target.value)}
+ placeholder="Name"
+ />
+ <input
+ type="email"
+ value={email}
+ onChange={(e) => setEmail(e.target.value)}
+ placeholder="Email"
+ />
+ <button type="submit">Submit</button>
+ </form>
+ );
+};
+```
+
+</TabItem>
+
+</Tabs>
+
+</Step>
+
+</Steps>
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
index 7cde66270..64d077ef1 100644
--- a/docs/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -182,7 +182,7 @@ const config: Config = {
},
prism: {
theme: prismThemes.nightOwlLight,
- darkTheme: prismThemes.nightOwl,
+ darkTheme: prismThemes.vsDark,
},
} satisfies Preset.ThemeConfig,
plugins: [