在你的 Astro 專案中整合 Mastra

本指南將帶你使用 Mastra 建立可呼叫 Tool 的 AI Agent，接著直接從路由匯入並呼叫 Agent，將它連接至 Astro。

你將使用 AI SDK UI 和 AI Elements，建立美觀且可互動的聊天體驗。

備註

本指南示範如何搭配 React 與完整伺服器端算繪（SSR）使用 Astro，但 Astro 與 Mastra 還有許多其他搭配方式。你可以針對個別檔案選擇啟用 SSR，並使用 Svelte、Vue、Solid 或 Preact 等其他框架。你也可以使用 Astro 建立聊天介面，並透過 Astro 原生方式呼叫端點。

開始之前
「開始之前」的直接連結

你需要受支援模型 Provider 的 API 金鑰。如果沒有偏好，請使用 OpenAI。
安裝 Node.js v22.13.0 或更新版本

建立新的 Astro 應用程式（選用）
「建立新的 Astro 應用程式（選用）」的直接連結

如果你已經有 Astro 應用程式，請跳到下一個步驟。你的 Astro 應用程式應依照下列方式設定：

使用 SSR（在 astro.config.mjs 中設定 output: "server"）
使用 React 整合
已安裝 Tailwind

為了支援隨選算繪，本指南會使用 Node.js adapter，但任何受支援的伺服器 adapter 都可以使用。

npm
pnpm
Yarn
Bun

npm create astro@latest mastra-astro -- --add node --add react --add tailwind --install --skip-houston --template minimal --git

pnpm create astro mastra-astro --add node --add react --add tailwind --install --skip-houston --template minimal --git

yarn create astro mastra-astro --add node --add react --add tailwind --install --skip-houston --template minimal --git

bunx create-astro mastra-astro --add node --add react --add tailwind --install --skip-houston --template minimal --git

這會建立名為 mastra-astro 的專案，但你可以替換成任何想要的名稱。

使用 cd 進入專案，接著編輯 astro.config.mjs 檔案，將 output 設定設為 "server"：

// @ts-check
import { defineConfig } from 'astro/config'

import node from '@astrojs/node'
import react from '@astrojs/react'
import tailwindcss from '@tailwindcss/vite'

// https://astro.build/config
export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),

  integrations: [react()],

  vite: {
    plugins: [tailwindcss()],
  },
})

編輯 tsconfig.json 以解析路徑：

tsconfig.json
{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
    },
    // ...
  },
}

初始化 Mastra
「初始化 Mastra」的直接連結

執行 mastra init。出現提示時，選擇 Provider（例如 OpenAI）並輸入金鑰：

npm
pnpm
Yarn
Bun

npx mastra@latest init

pnpm dlx mastra@latest init

yarn dlx mastra@latest init

bun x mastra@latest init

這會建立 src/mastra 資料夾，其中包含範例天氣 Agent 和下列檔案：

index.ts - Mastra 設定，包含記憶功能
tools/weather-tool.ts - 擷取指定位置天氣資訊的 Tool
agents/weather-agent.ts- 使用該 Tool 的天氣 Agent，並包含提示詞

在接下來的步驟中，你會從 Astro 路由呼叫 weather-agent.ts。

安裝 AI SDK UI 與 AI Elements
「安裝 AI SDK UI 與 AI Elements」的直接連結

安裝 AI SDK UI 與 Mastra adapter：

npm
pnpm
Yarn
Bun

npm install @mastra/ai-sdk@latest @ai-sdk/react ai

pnpm add @mastra/ai-sdk@latest @ai-sdk/react ai

yarn add @mastra/ai-sdk@latest @ai-sdk/react ai

bun add @mastra/ai-sdk@latest @ai-sdk/react ai

接著初始化 AI Elements。出現提示時，選擇預設選項：

npm
pnpm
Yarn
Bun

npx ai-elements@latest

pnpm dlx ai-elements@latest

yarn dlx ai-elements@latest

bun x ai-elements@latest

這會將完整的 AI Elements UI 元件庫下載至 @/components/ai-elements 資料夾。

建立聊天路由
「建立聊天路由」的直接連結

建立 src/pages/api/chat.ts：

src/pages/api/chat.ts
import type { APIRoute } from 'astro'
import { handleChatStream } from '@mastra/ai-sdk'
import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
import { createUIMessageStreamResponse } from 'ai'
import { mastra } from '@/mastra'

const THREAD_ID = 'example-user-id'
const RESOURCE_ID = 'weather-chat'

export const POST: APIRoute = async ({ request }) => {
  const params = await request.json()
  const stream = await handleChatStream({
    mastra,
    agentId: 'weather-agent',
    params: {
      ...params,
      memory: {
        ...params.memory,
        thread: THREAD_ID,
        resource: RESOURCE_ID,
      },
    },
  })

  return createUIMessageStreamResponse({ stream })
}

export const GET: APIRoute = async () => {
  const memory = await mastra.getAgentById('weather-agent').getMemory()
  let response = null

  try {
    response = await memory?.recall({
      threadId: THREAD_ID,
      resourceId: RESOURCE_ID,
    })
  } catch {
    console.log('No previous messages found.')
  }

  const uiMessages = toAISdkV5Messages(response?.messages || [])

  return Response.json(uiMessages)
}

POST 路由會接收提示詞，並以 AI SDK 格式串流回傳 Agent 的回應；GET 路由則從記憶中擷取訊息記錄，讓使用者端重新載入時能還原 UI 狀態。

建立聊天元件
「建立聊天元件」的直接連結

建立 src/components/chat.tsx：

src/components/chat.tsx
import '@/styles/global.css'
import { useEffect, useState } from 'react'
import { DefaultChatTransport, type ToolUIPart } from 'ai'
import { useChat } from '@ai-sdk/react'

import {
  PromptInput,
  PromptInputBody,
  PromptInputTextarea,
} from '@/components/ai-elements/prompt-input'

import {
  Conversation,
  ConversationContent,
  ConversationScrollButton,
} from '@/components/ai-elements/conversation'

import { Message, MessageContent, MessageResponse } from '@/components/ai-elements/message'

import { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput } from '@/components/ai-elements/tool'

function Chat() {
  const [input, setInput] = useState<string>('')

  const { messages, setMessages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({
      api: '/api/chat',
    }),
  })

  useEffect(() => {
    const fetchMessages = async () => {
      const res = await fetch('/api/chat')
      const data = await res.json()
      setMessages([...data])
    }
    fetchMessages()
  }, [setMessages])

  const handleSubmit = async () => {
    if (!input.trim()) return

    sendMessage({ text: input })
    setInput('')
  }

  return (
    <div className="relative size-full h-screen w-full p-6">
      <div className="flex h-full flex-col">
        <Conversation className="h-full">
          <ConversationContent>
            {messages.map(message => (
              <div key={message.id}>
                {message.parts?.map((part, i) => {
                  if (part.type === 'text') {
                    return (
                      <Message key={`${message.id}-${i}`} from={message.role}>
                        <MessageContent>
                          <MessageResponse>{part.text}</MessageResponse>
                        </MessageContent>
                      </Message>
                    )
                  }

                  if (part.type?.startsWith('tool-')) {
                    return (
                      <Tool key={`${message.id}-${i}`}>
                        <ToolHeader
                          type={(part as ToolUIPart).type}
                          state={(part as ToolUIPart).state || 'output-available'}
                          className="cursor-pointer"
                        />
                        <ToolContent>
                          <ToolInput input={(part as ToolUIPart).input || {}} />
                          <ToolOutput
                            output={(part as ToolUIPart).output}
                            errorText={(part as ToolUIPart).errorText}
                          />
                        </ToolContent>
                      </Tool>
                    )
                  }

                  return null
                })}
              </div>
            ))}
            <ConversationScrollButton />
          </ConversationContent>
        </Conversation>

        <PromptInput onSubmit={handleSubmit} className="mt-20">
          <PromptInputBody>
            <PromptInputTextarea
              onChange={e => setInput(e.target.value)}
              className="md:leading-10"
              value={input}
              placeholder="Type your message..."
              disabled={status !== 'ready'}
            />
          </PromptInputBody>
        </PromptInput>
      </div>
    </div>
  )
}

export default Chat

此元件會將 useChat() 連接至 api/chat 端點，將提示詞傳送至該端點，並以分段串流方式回傳回應。

它會使用 <MessageResponse> 元件算繪回應文字，並透過 <Tool> 元件顯示所有 Tool 呼叫。

算繪聊天元件
「算繪聊天元件」的直接連結

最後一步是在索引頁面上算繪聊天元件。編輯 src/pages/index.astro：

src/pages/index.astro
---
import Chat from '@/components/chat';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <meta name="generator" content="{Astro.generator}" />
    <title>Astro</title>
  </head>
  <body>
    <Chat client:load />
  </body>
</html>

匯入 Chat 元件，並使用 client:load 指令將它加入 body，使其在使用者端執行。

測試你的 Agent
「測試你的 Agent」的直接連結

使用 npm run dev 執行 Astro 應用程式
在 http://localhost:4321 開啟聊天介面
試著詢問天氣。如果 API 金鑰設定正確，你會收到回應

後續步驟
「後續步驟」的直接連結

恭喜你使用 Astro 建立了 Mastra Agent！🎉

接下來，你可以使用自己的 Tool 和邏輯擴充專案：

深入了解 Agent
為 Agent 加入專屬的 Tool
為 Agent 加入類似人類的記憶

準備好後，進一步了解 Mastra 如何與 AI SDK UI 整合，以及如何將 Agent 部署至任何地方：

將 Mastra 與 AI SDK UI 整合
將 Agent 部署至任何地方

開始之前「開始之前」的直接連結

建立新的 Astro 應用程式（選用）「建立新的 Astro 應用程式（選用）」的直接連結

初始化 Mastra「初始化 Mastra」的直接連結

安裝 AI SDK UI 與 AI Elements「安裝 AI SDK UI 與 AI Elements」的直接連結

建立聊天路由「建立聊天路由」的直接連結

建立聊天元件「建立聊天元件」的直接連結

算繪聊天元件「算繪聊天元件」的直接連結

測試你的 Agent「測試你的 Agent」的直接連結

後續步驟「後續步驟」的直接連結