> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# Next.js プロジェクトに Mastra を統合する

このガイドでは、Mastra を使用して Tool を呼び出す AI Agent を構築し、ルートから Agent を直接 import して呼び出すことで Next.js に接続します。

[AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) と [AI Elements](https://ai-sdk.dev/elements) を使用して、美しくインタラクティブなチャット体験を作成します。

## 始める前に

- サポートされている[モデル Provider](https://mastra.zisheng.pro/ja/models) の API キーが必要です。特に希望がなければ、[OpenAI](https://mastra.zisheng.pro/ja/models/providers/openai) を使用してください。
- Node.js `v22.13.0` 以降をインストールしてください

## 新しい Next.js アプリを作成する（任意）

Next.js アプリがすでにある場合は、次の手順に進んでください。

次のコマンドを実行して、[新しい Next.js アプリを作成](https://nextjs.org/docs/app/getting-started/installation)します。

**npm**:

```bash
npx create-next-app@latest my-nextjs-agent --yes --ts --eslint --tailwind --src-dir --app --turbopack --no-react-compiler --no-import-alias
```

**pnpm**:

```bash
pnpm dlx create-next-app@latest my-nextjs-agent --yes --ts --eslint --tailwind --src-dir --app --turbopack --no-react-compiler --no-import-alias
```

**Yarn**:

```bash
yarn dlx create-next-app@latest my-nextjs-agent --yes --ts --eslint --tailwind --src-dir --app --turbopack --no-react-compiler --no-import-alias
```

**Bun**:

```bash
bun x create-next-app@latest my-nextjs-agent --yes --ts --eslint --tailwind --src-dir --app --turbopack --no-react-compiler --no-import-alias
```

これにより `my-nextjs-agent` というプロジェクトが作成されますが、任意の名前に置き換えられます。

## Mastra を初期化する

Next.js プロジェクトに移動します。

```bash
cd my-nextjs-agent
```

[`mastra init`](https://mastra.zisheng.pro/ja/reference/cli/mastra) を実行します。プロンプトが表示されたら、Provider（OpenAI など）を選択してキーを入力します。

**npm**:

```bash
npx mastra@latest init
```

**pnpm**:

```bash
pnpm dlx mastra@latest init
```

**Yarn**:

```bash
yarn dlx mastra@latest init
```

**Bun**:

```bash
bun x mastra@latest init
```

これにより、天気 Agent のサンプルと次のファイルを含む `src/mastra` フォルダーが作成されます。

- `index.ts` - Memory を含む Mastra の設定
- `tools/weather-tool.ts` - 指定した場所の天気を取得する Tool
- `agents/weather-agent.ts`- Tool を使用するプロンプトを備えた天気 Agent

次の手順では、Next.js のルートから `weather-agent.ts` を呼び出します。

> **Next.js と Studio を併用する:** Next.js アプリと並行して [Studio](https://mastra.zisheng.pro/ja/docs/studio/overview) を実行し、両方で同じデータベースを共有する場合は、`src/mastra/index.ts` の Storage URL を絶対パスに変更します。
>
> ```typescript
> url: 'file:/absolute/path/to/your/project/mastra.db'
> ```
>
> 相対パスは各プロセスの作業ディレクトリを基準に解決されますが、`next dev` と `mastra dev` ではそのディレクトリが異なります。

## AI SDK UI と AI Elements をインストールする

AI SDK UI と Mastra アダプターをインストールします。

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

次に、AI Elements を初期化します。プロンプトが表示されたら、デフォルトのオプションを選択してください。

**npm**:

```bash
npx ai-elements@latest
```

**pnpm**:

```bash
pnpm dlx ai-elements@latest
```

**Yarn**:

```bash
yarn dlx ai-elements@latest
```

**Bun**:

```bash
bun x ai-elements@latest
```

これにより、AI Elements の UI コンポーネントライブラリ全体が `@/components/ai-elements` フォルダーにダウンロードされます。

## チャットルートを作成する

`src/app/api/chat/route.ts` を作成します。

```ts
import { handleChatStream } from '@mastra/ai-sdk'
import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
import { createUIMessageStreamResponse } from 'ai'
import { mastra } from '@/mastra'
import { NextResponse } from 'next/server'

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

export async function POST(req: Request) {
  const params = await req.json()
  const stream = await handleChatStream({
    mastra,
    agentId: 'weather-agent',
    params: {
      ...params,
      memory: {
        ...params.memory,
        thread: THREAD_ID,
        resource: RESOURCE_ID,
      },
    },
  })
  return createUIMessageStreamResponse({ stream })
}

export async function GET() {
  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 NextResponse.json(uiMessages)
}
```

`POST` ルートはプロンプトを受け取り、Agent のレスポンスを AI SDK 形式でストリーミングします。一方、`GET` ルートは Memory からメッセージ履歴を取得し、クライアントの再読み込み時に UI を復元できるようにします。

## チャットページを作成する

`src/app/chat/page.tsx` を作成します。

```tsx
'use client'

import '@/app/globals.css'
import { useEffect, useState } from 'react'
import { DefaultChatTransport, 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()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) を `api/chat` エンドポイントに接続し、そこへプロンプトを送信して、レスポンスをチャンク単位でストリーミングします。

レスポンスのテキストは [`<MessageResponse>`](https://ai-sdk.dev/elements/components/message#messageresponse-) コンポーネントでレンダリングされ、Tool の呼び出しは [`<Tool>`](https://ai-sdk.dev/elements/components/tool) コンポーネントで表示されます。

## Agent をテストする

1. `npm run dev` で Next.js アプリを実行します
2. <http://localhost:3000/chat> でチャットを開きます
3. 天気について質問してみます。API キーが正しく設定されていれば、レスポンスが返されます

## 次のステップ

Next.js で Mastra Agent を構築できました！🎉

ここから、独自の Tool やロジックを追加してプロジェクトを拡張できます。

- [Agent](https://mastra.zisheng.pro/ja/docs/agents/overview) について詳しく学ぶ
- Agent に独自の [Tool](https://mastra.zisheng.pro/ja/docs/agents/using-tools) を追加する
- Agent に人間のような [Memory](https://mastra.zisheng.pro/ja/docs/memory/overview) を追加する

準備ができたら、Mastra と AI SDK UI および Next.js の統合方法や、Vercel を含む任意の場所へ Agent をデプロイする方法について詳しく学びましょう。

- Mastra を [AI SDK UI](https://mastra.zisheng.pro/ja/guides/build-your-ui/ai-sdk-ui) と統合する
- Agent を [Vercel](https://mastra.zisheng.pro/ja/guides/deployment/vercel) にデプロイする
- Agent を[任意の場所](https://mastra.zisheng.pro/ja/docs/deployment/overview)にデプロイする