creating-agents-in-medusa

Medusa でのエージェントの作成

このスキルでは、Medusa プロジェクトに内部向けの管理者用AI エージェントを追加するためのフルスタックを解説します。これらのエージェントは、ストアフロントの顧客ではなく、Medusa 管理ダッシュボードを通じてマーチャントやストア運営者が使用します。顧客向けエージェント（例：ストアフロントのチャットボット）には、別のアーキテクチャが必要です。公開 API ルートを使用し、MedusaExec は使わず、ストアフロントの認証を用います。

制約事項

• 内部利用のみ — このアーキテクチャは管理ユーザー（マーチャント、運営者、サポートスタッフ）向けであり、顧客向けではありません。ルートは src/api/admin/ 配下に配置し、UI は Medusa 管理ダッシュボードに配置します。また、すべてのアクセスは管理者認証によって制限されます。
• 認証は必須です — MedusaExec は、データベースへのフルアクセスを伴う任意の TypeScript を実行します。すべてのエージェントルートで AuthenticatedMedusaRequest を使用し、src/api/admin/ 配下に配置してください。認証されていないエンドポイントは、リモートコード実行の脆弱性になります。
• カスタムツールではなく MedusaExec を使用します — データ操作では、エージェントが TypeScript を記述し、MedusaExec を介して実行します。実行可能な TypeScript では表現できない機能（例：シークレットキーを使った外部 API の呼び出し）に限り、カスタムツールを作成してください。
• 共有モジュールを 1 つ、エージェントを複数作成します — AgentSession と AgentMessage は共有インフラストラクチャです。エージェントごとのセッションを区別するには agent_type を使用してください。エージェントごとに別のモデルを作成しないでください。
• experimental_context 経由で MedusaContainer を渡します — ツールファイルからサービスを直接インポートしないでください。循環依存が発生します。
• ストリーム形式は NDJSON です — Content-Type: application/x-ndjson を使用し、1 行につき JSON オブジェクトを 1 つ出力し、行末には \n を付けます。
• モデルを追加または変更した後はマイグレーションを実行します（npx medusa db:generate agent && npx medusa db:migrate）。
• ツールの説明は tool() 内ではなく、設定に記述します — 設定オブジェクトが実行時にツールの説明を上書きします。

重要：必要に応じてリファレンスファイルを読み込む

⚠️ 以下のクイックリファレンスだけでは実装には不十分です。 コードを書く前に、該当するリファレンスファイルを読み込んでください。

タスク	読み込むファイル
会話モデルの定義	reference/data-models.md
モジュールサービスの設定	reference/service.md
ツール、プロンプト、streamText の設定	reference/agent-setup.md
POST チャットエンドポイントの構築	reference/api-route.md
NDJSON ストリーミングの実装	reference/streaming.md
管理画面のチャット UI の構築	reference/admin-extension.md
エージェントへのコード実行機能の付与	reference/medusa-exec.md

最低要件： コードを書く前に、現在のタスクに対応するリファレンスファイルを少なくとも 1 つ読み込んでください。

関連スキル

必要に応じて、このスキルと併せて以下を読み込んでください。

• building-with-medusa — Medusa のモジュールパターン、ワークフロー、データモデルの規約について説明します。モジュールサービスやカスタムバックエンドロジックを実装する際に読み込んでください。
• building-admin-dashboard-customizations — 管理 UI のコンポーネントパターン、TanStack Query、ルート登録について説明します。管理画面のチャット UI を構築または拡張する際に読み込んでください。

アーキテクチャの概要

src/modules/agent/
  index.ts                ← Module() export + AGENT_MODULE constant
  service.ts              ← MedusaService + Anthropic client + stream(messages, container, config)
  models/
    session.ts            ← AgentSession (shared across all agents, filtered by agent_type)
    message.ts            ← AgentMessage
  agents/index.ts         ← streamText() orchestration
  tools/
    medusa-exec.ts        ← MedusaExec tool (primary tool for all data operations)
    todo-write.ts         ← TodoWrite tool
  config/
    <agent-type>.ts       ← per-agent system prompt + tool descriptions

src/api/admin/agent/<agent-type>/
  route.ts                ← POST (AuthenticatedMedusaRequest, session lifecycle, NDJSON stream)
  sessions/route.ts       ← GET session list (filtered by agent_type)
  sessions/[id]/route.ts  ← GET messages for a session

src/admin/routes/<agent-type>/
  page.tsx                ← React chat UI (admin extension)

src/lib/code-mode/
  executor.ts             ← sandboxed TypeScript executor used by MedusaExec

よくある間違い

以下の操作をしていないことを確認してください。

セキュリティ：

• エージェントのルートで AuthenticatedMedusaRequest ではなく MedusaRequest を使用している
• エージェントのルートを src/api/admin/ の外に配置している

アーキテクチャ：

• agent_type を使用せず、エージェントごとに個別の AgentSession／AgentMessage モデルを作成している
• experimental_context からサービスを解決せず、ツールファイル内でサービスを直接インポートしている
• MedusaExec を使用せず、データ操作用のカスタムツールを作成している

ストリーミング：

• ストリームのループ後に res.end() がなく、レスポンスが終了しない
• Transfer-Encoding: chunked または Content-Type: application/x-ndjson ヘッダーがない
• クライアントで不完全な行をバッファリングしておらず、パケット分割時に JSON の解析エラーが発生する

モジュール：

• medusa-config.ts へのモジュールの登録を忘れている
• モデル変更後のマイグレーション実行を忘れている
• tool() ではなく設定オブジェクトに記述すべきツールの説明を、tool() 内にハードコードしている

利用可能なリファレンスファイル

reference/data-models.md       - model.define(), agent_type discriminator, relationships, migrations
reference/service.md           - MedusaService extension, Anthropic init, stream(), module index, config registration
reference/agent-setup.md       - streamText(), MedusaExec tool wiring, system prompt, context passing
reference/api-route.md         - POST route, session lifecycle, message persistence, streaming headers
reference/streaming.md         - NDJSON emission, fullStream iteration, chunk types, client-side parsing
reference/admin-extension.md   - React chat UI, streaming fetch, message rendering, tool call display, session sidebar
reference/medusa-exec.md       - Executor setup, MedusaExec tool, query.graph() patterns, error codes

テスト

エージェントを実装したら、管理ダッシュボードから直接エンドツーエンドでテストします。

1. Medusa 開発サーバーを起動します（npx medusa develop）
2. 管理ダッシュボードを開き、サイドバーにあるエージェントのページに移動します（defineRouteConfig で設定したラベルが表示されます）
3. 「ストアには商品がいくつありますか？」 など、シンプルな読み取り専用プロンプトを入力して送信します
4. レスポンスがストリーミングされ、サイドバーに新しいセッションが表示されることを確認します
5. 同じセッションでフォローアップメッセージを送信し、会話履歴が保持されることを確認します
6. ページを再読み込みし、サイドバーからセッションを選択して、データベースからメッセージ履歴が復元されることを確認します

問題が発生した場合は、次を確認してください。

• ブラウザーのネットワークタブ — POST リクエストが Content-Type: application/x-ndjson を返し、チャンク化された行が含まれていることを確認します
• サーバーログ — [agent] tool_call と [agent] step_finish の行があれば、エージェントが実行されています
• データベース — agent_session と agent_message テーブルに、正しい agent_type の行があることを確認します