/creating-internal-agents

name: creating-agents-in-medusa
description: "Use when building an internal admin-facing AI agent in a Medusa project. These agents are operated by merchants and store operators — not customers. Covers data models, module service, agent runtime (tools, system prompt, streamText), streaming API routes (NDJSON), and admin UI chat extensions. Load for any internal agent type: store operations assistant, product audit, cohort analysis, customer service tooling for support staff, etc. Do NOT use for customer-facing agents (storefront chatbots, buyer-side assistants)."

Creating Agents in Medusa

This skill covers the full stack for adding an **internal, admin-facing** AI agent to a Medusa project. These agents are used by merchants and store operators through the Medusa admin dashboard — not by customers on a storefront. For customer-facing agents (e.g. a storefront chatbot), a different architecture is needed: public API routes, no MedusaExec, and storefront auth.

Constraints

• **Internal use only** — this architecture is for admin users (merchants, operators, support staff), not customers. Routes live under `src/api/admin/`, the UI lives in the Medusa admin dashboard, and access is gated by admin authentication throughout.
• **Authentication is non-negotiable** — MedusaExec runs arbitrary TypeScript with full database access. All agent routes must use `AuthenticatedMedusaRequest` and live under `src/api/admin/`. An unauthenticated endpoint is a remote code execution vulnerability.
• **Use MedusaExec, not custom tools** — for any data operation, the agent writes TypeScript and executes it via MedusaExec. Only build a custom tool for capabilities that cannot be expressed as executable TypeScript (e.g. calling an external API with a secret key).
• **One shared module, multiple agents** — `AgentSession` and `AgentMessage` are shared infrastructure. Use `agent_type` to distinguish sessions per agent. Never create separate models per agent.
• **Pass `MedusaContainer` via `experimental_context`** — never import services directly in tool files; that causes circular dependencies.
• **Stream format is NDJSON** — `Content-Type: application/x-ndjson`, one JSON object per line followed by `\n`.
• **Run migrations** after adding or changing models (`npx medusa db:generate agent && npx medusa db:migrate`).
• **Tool descriptions live in config**, not inline in `tool()` — the config object overrides them at runtime.

CRITICAL: Load Reference Files When Needed

**⚠️ The quick reference below is NOT sufficient for implementation.** Load the relevant reference file before writing any code.

| Task | Load this file | |------|---------------| | Defining conversation models | `reference/data-models.md` | | Setting up the module service | `reference/service.md` | | Configuring tools, prompt, streamText | `reference/agent-setup.md` | | Building the POST chat endpoint | `reference/api-route.md` | | Implementing NDJSON streaming | `reference/streaming.md` | | Building the admin chat UI | `reference/admin-extension.md` | | Giving the agent code execution capability | `reference/medusa-exec.md` |

**Minimum requirement:** Load at least the reference file matching your current task before writing code.

Related Skills

Load these alongside this skill when relevant:

• **`building-with-medusa`** — Medusa module patterns, workflows, data model conventions. Load when implementing the module service or custom backend logic.
• **`building-admin-dashboard-customizations`** — Admin UI component patterns, TanStack Query, route registration. Load when building or extending the admin chat UI.

Architecture Overview

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

Common Mistakes

Verify you are NOT doing these:

**Security:**

• [ ] Agent route uses `MedusaRequest` instead of `AuthenticatedMedusaRequest`
• [ ] Agent route placed outside `src/api/admin/`

**Architecture:**

• [ ] Creating separate `AgentSession`/`AgentMessage` models per agent instead of using `agent_type`
• [ ] Importing services directly in tool files instead of resolving from `experimental_context`
• [ ] Building a custom tool for a data operation instead of using MedusaExec

**Streaming:**

• [ ] Missing `res.end()` after the stream loop (response never closes)
• [ ] Missing `Transfer-Encoding: chunked` or `Content-Type: application/x-ndjson` headers
• [ ] Not buffering incomplete lines on the client (JSON parse errors on split packets)

**Module:**

• [ ] Forgetting to register the module in `medusa-config.ts`
• [ ] Forgetting to run migrations after changing models
• [ ] Hardcoding tool descriptions in `tool()` instead of the config object

Reference Files Available

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 to