[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-medusa-creating-agents-in-medusa":3,"mdc--x2uz9p-key":37,"related-repo-medusa-creating-agents-in-medusa":870,"related-org-medusa-creating-agents-in-medusa":961},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":12,"stars":21,"repoUrl":22,"updatedAt":23,"license":24,"forks":25,"topics":26,"repo":32,"sourceUrl":35,"mdContent":36},"creating-agents-in-medusa","build admin-facing AI agents in Medusa","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).",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},"medusa","Medusa","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fmedusa.jpg","medusajs",[13,17,18],{"name":14,"slug":15,"type":16},"Backend","backend","tag",{"name":9,"slug":8,"type":16},{"name":19,"slug":20,"type":16},"Agents","agents",197,"https:\u002F\u002Fgithub.com\u002Fmedusajs\u002Fmedusa-agent-skills","2026-07-14T05:42:09.367168",null,24,[27,28,29,30,31,8],"agentic-commerce","claude","claude-code","commerce","ecommerce",{"repoUrl":22,"stars":21,"forks":25,"topics":33,"description":34},[27,28,29,30,31,8],"Agent skills and commands for Medusa best practices and conventions.","https:\u002F\u002Fgithub.com\u002Fmedusajs\u002Fmedusa-agent-skills\u002Ftree\u002FHEAD\u002Fplugins\u002Fmedusa-dev\u002Fskills\u002Fcreating-internal-agents","---\nname: creating-agents-in-medusa\ndescription: \"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).\"\n---\n\n# Creating Agents in Medusa\n\nThis 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.\n\n## Constraints\n\n- **Internal use only** — this architecture is for admin users (merchants, operators, support staff), not customers. Routes live under `src\u002Fapi\u002Fadmin\u002F`, the UI lives in the Medusa admin dashboard, and access is gated by admin authentication throughout.\n- **Authentication is non-negotiable** — MedusaExec runs arbitrary TypeScript with full database access. All agent routes must use `AuthenticatedMedusaRequest` and live under `src\u002Fapi\u002Fadmin\u002F`. An unauthenticated endpoint is a remote code execution vulnerability.\n- **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).\n- **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.\n- **Pass `MedusaContainer` via `experimental_context`** — never import services directly in tool files; that causes circular dependencies.\n- **Stream format is NDJSON** — `Content-Type: application\u002Fx-ndjson`, one JSON object per line followed by `\\n`.\n- **Run migrations** after adding or changing models (`npx medusa db:generate agent && npx medusa db:migrate`).\n- **Tool descriptions live in config**, not inline in `tool()` — the config object overrides them at runtime.\n\n## CRITICAL: Load Reference Files When Needed\n\n**⚠️ The quick reference below is NOT sufficient for implementation.** Load the relevant reference file before writing any code.\n\n| Task | Load this file |\n|------|---------------|\n| Defining conversation models | `reference\u002Fdata-models.md` |\n| Setting up the module service | `reference\u002Fservice.md` |\n| Configuring tools, prompt, streamText | `reference\u002Fagent-setup.md` |\n| Building the POST chat endpoint | `reference\u002Fapi-route.md` |\n| Implementing NDJSON streaming | `reference\u002Fstreaming.md` |\n| Building the admin chat UI | `reference\u002Fadmin-extension.md` |\n| Giving the agent code execution capability | `reference\u002Fmedusa-exec.md` |\n\n**Minimum requirement:** Load at least the reference file matching your current task before writing code.\n\n## Related Skills\n\nLoad these alongside this skill when relevant:\n\n- **`building-with-medusa`** — Medusa module patterns, workflows, data model conventions. Load when implementing the module service or custom backend logic.\n- **`building-admin-dashboard-customizations`** — Admin UI component patterns, TanStack Query, route registration. Load when building or extending the admin chat UI.\n\n## Architecture Overview\n\n```\nsrc\u002Fmodules\u002Fagent\u002F\n  index.ts                ← Module() export + AGENT_MODULE constant\n  service.ts              ← MedusaService + Anthropic client + stream(messages, container, config)\n  models\u002F\n    session.ts            ← AgentSession (shared across all agents, filtered by agent_type)\n    message.ts            ← AgentMessage\n  agents\u002Findex.ts         ← streamText() orchestration\n  tools\u002F\n    medusa-exec.ts        ← MedusaExec tool (primary tool for all data operations)\n    todo-write.ts         ← TodoWrite tool\n  config\u002F\n    \u003Cagent-type>.ts       ← per-agent system prompt + tool descriptions\n\nsrc\u002Fapi\u002Fadmin\u002Fagent\u002F\u003Cagent-type>\u002F\n  route.ts                ← POST (AuthenticatedMedusaRequest, session lifecycle, NDJSON stream)\n  sessions\u002Froute.ts       ← GET session list (filtered by agent_type)\n  sessions\u002F[id]\u002Froute.ts  ← GET messages for a session\n\nsrc\u002Fadmin\u002Froutes\u002F\u003Cagent-type>\u002F\n  page.tsx                ← React chat UI (admin extension)\n\nsrc\u002Flib\u002Fcode-mode\u002F\n  executor.ts             ← sandboxed TypeScript executor used by MedusaExec\n```\n\n## Common Mistakes\n\nVerify you are NOT doing these:\n\n**Security:**\n- [ ] Agent route uses `MedusaRequest` instead of `AuthenticatedMedusaRequest`\n- [ ] Agent route placed outside `src\u002Fapi\u002Fadmin\u002F`\n\n**Architecture:**\n- [ ] Creating separate `AgentSession`\u002F`AgentMessage` models per agent instead of using `agent_type`\n- [ ] Importing services directly in tool files instead of resolving from `experimental_context`\n- [ ] Building a custom tool for a data operation instead of using MedusaExec\n\n**Streaming:**\n- [ ] Missing `res.end()` after the stream loop (response never closes)\n- [ ] Missing `Transfer-Encoding: chunked` or `Content-Type: application\u002Fx-ndjson` headers\n- [ ] Not buffering incomplete lines on the client (JSON parse errors on split packets)\n\n**Module:**\n- [ ] Forgetting to register the module in `medusa-config.ts`\n- [ ] Forgetting to run migrations after changing models\n- [ ] Hardcoding tool descriptions in `tool()` instead of the config object\n\n## Reference Files Available\n\n```\nreference\u002Fdata-models.md       - model.define(), agent_type discriminator, relationships, migrations\nreference\u002Fservice.md           - MedusaService extension, Anthropic init, stream(), module index, config registration\nreference\u002Fagent-setup.md       - streamText(), MedusaExec tool wiring, system prompt, context passing\nreference\u002Fapi-route.md         - POST route, session lifecycle, message persistence, streaming headers\nreference\u002Fstreaming.md         - NDJSON emission, fullStream iteration, chunk types, client-side parsing\nreference\u002Fadmin-extension.md   - React chat UI, streaming fetch, message rendering, tool call display, session sidebar\nreference\u002Fmedusa-exec.md       - Executor setup, MedusaExec tool, query.graph() patterns, error codes\n```\n\n## Testing\n\nOnce the agent is implemented, test it end-to-end directly in the admin dashboard:\n\n1. Start the Medusa dev server (`npx medusa develop`)\n2. Open the admin dashboard and navigate to the agent's page in the sidebar (the label set in `defineRouteConfig`)\n3. Type a simple read-only prompt — e.g. *\"How many products are in the store?\"* — and submit\n4. Verify the response streams in and a new session appears in the sidebar\n5. Send a follow-up message in the same session to confirm conversation history is preserved\n6. Reload the page, select the session from the sidebar, and confirm the message history is restored from the database\n\nIf anything is broken, check:\n- Browser network tab — the POST request should return `Content-Type: application\u002Fx-ndjson` with chunked lines\n- Server logs — `[agent] tool_call` and `[agent] step_finish` lines confirm the agent is running\n- Database — `agent_session` and `agent_message` tables should have rows with the correct `agent_type`\n",{"data":38,"body":39},{"name":4,"description":6},{"type":40,"children":41},"root",[42,50,64,71,249,255,265,412,422,428,433,464,470,482,488,493,501,546,554,609,617,670,678,722,728,737,743,748,805,810],{"type":43,"tag":44,"props":45,"children":46},"element","h1",{"id":4},[47],{"type":48,"value":49},"text","Creating Agents in Medusa",{"type":43,"tag":51,"props":52,"children":53},"p",{},[54,56,62],{"type":48,"value":55},"This skill covers the full stack for adding an ",{"type":43,"tag":57,"props":58,"children":59},"strong",{},[60],{"type":48,"value":61},"internal, admin-facing",{"type":48,"value":63}," 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.",{"type":43,"tag":65,"props":66,"children":68},"h2",{"id":67},"constraints",[69],{"type":48,"value":70},"Constraints",{"type":43,"tag":72,"props":73,"children":74},"ul",{},[75,95,120,130,164,188,213,231],{"type":43,"tag":76,"props":77,"children":78},"li",{},[79,84,86,93],{"type":43,"tag":57,"props":80,"children":81},{},[82],{"type":48,"value":83},"Internal use only",{"type":48,"value":85}," — this architecture is for admin users (merchants, operators, support staff), not customers. Routes live under ",{"type":43,"tag":87,"props":88,"children":90},"code",{"className":89},[],[91],{"type":48,"value":92},"src\u002Fapi\u002Fadmin\u002F",{"type":48,"value":94},", the UI lives in the Medusa admin dashboard, and access is gated by admin authentication throughout.",{"type":43,"tag":76,"props":96,"children":97},{},[98,103,105,111,113,118],{"type":43,"tag":57,"props":99,"children":100},{},[101],{"type":48,"value":102},"Authentication is non-negotiable",{"type":48,"value":104}," — MedusaExec runs arbitrary TypeScript with full database access. All agent routes must use ",{"type":43,"tag":87,"props":106,"children":108},{"className":107},[],[109],{"type":48,"value":110},"AuthenticatedMedusaRequest",{"type":48,"value":112}," and live under ",{"type":43,"tag":87,"props":114,"children":116},{"className":115},[],[117],{"type":48,"value":92},{"type":48,"value":119},". An unauthenticated endpoint is a remote code execution vulnerability.",{"type":43,"tag":76,"props":121,"children":122},{},[123,128],{"type":43,"tag":57,"props":124,"children":125},{},[126],{"type":48,"value":127},"Use MedusaExec, not custom tools",{"type":48,"value":129}," — 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).",{"type":43,"tag":76,"props":131,"children":132},{},[133,138,140,146,148,154,156,162],{"type":43,"tag":57,"props":134,"children":135},{},[136],{"type":48,"value":137},"One shared module, multiple agents",{"type":48,"value":139}," — ",{"type":43,"tag":87,"props":141,"children":143},{"className":142},[],[144],{"type":48,"value":145},"AgentSession",{"type":48,"value":147}," and ",{"type":43,"tag":87,"props":149,"children":151},{"className":150},[],[152],{"type":48,"value":153},"AgentMessage",{"type":48,"value":155}," are shared infrastructure. Use ",{"type":43,"tag":87,"props":157,"children":159},{"className":158},[],[160],{"type":48,"value":161},"agent_type",{"type":48,"value":163}," to distinguish sessions per agent. Never create separate models per agent.",{"type":43,"tag":76,"props":165,"children":166},{},[167,186],{"type":43,"tag":57,"props":168,"children":169},{},[170,172,178,180],{"type":48,"value":171},"Pass ",{"type":43,"tag":87,"props":173,"children":175},{"className":174},[],[176],{"type":48,"value":177},"MedusaContainer",{"type":48,"value":179}," via ",{"type":43,"tag":87,"props":181,"children":183},{"className":182},[],[184],{"type":48,"value":185},"experimental_context",{"type":48,"value":187}," — never import services directly in tool files; that causes circular dependencies.",{"type":43,"tag":76,"props":189,"children":190},{},[191,196,197,203,205,211],{"type":43,"tag":57,"props":192,"children":193},{},[194],{"type":48,"value":195},"Stream format is NDJSON",{"type":48,"value":139},{"type":43,"tag":87,"props":198,"children":200},{"className":199},[],[201],{"type":48,"value":202},"Content-Type: application\u002Fx-ndjson",{"type":48,"value":204},", one JSON object per line followed by ",{"type":43,"tag":87,"props":206,"children":208},{"className":207},[],[209],{"type":48,"value":210},"\\n",{"type":48,"value":212},".",{"type":43,"tag":76,"props":214,"children":215},{},[216,221,223,229],{"type":43,"tag":57,"props":217,"children":218},{},[219],{"type":48,"value":220},"Run migrations",{"type":48,"value":222}," after adding or changing models (",{"type":43,"tag":87,"props":224,"children":226},{"className":225},[],[227],{"type":48,"value":228},"npx medusa db:generate agent && npx medusa db:migrate",{"type":48,"value":230},").",{"type":43,"tag":76,"props":232,"children":233},{},[234,239,241,247],{"type":43,"tag":57,"props":235,"children":236},{},[237],{"type":48,"value":238},"Tool descriptions live in config",{"type":48,"value":240},", not inline in ",{"type":43,"tag":87,"props":242,"children":244},{"className":243},[],[245],{"type":48,"value":246},"tool()",{"type":48,"value":248}," — the config object overrides them at runtime.",{"type":43,"tag":65,"props":250,"children":252},{"id":251},"critical-load-reference-files-when-needed",[253],{"type":48,"value":254},"CRITICAL: Load Reference Files When Needed",{"type":43,"tag":51,"props":256,"children":257},{},[258,263],{"type":43,"tag":57,"props":259,"children":260},{},[261],{"type":48,"value":262},"⚠️ The quick reference below is NOT sufficient for implementation.",{"type":48,"value":264}," Load the relevant reference file before writing any code.",{"type":43,"tag":266,"props":267,"children":268},"table",{},[269,288],{"type":43,"tag":270,"props":271,"children":272},"thead",{},[273],{"type":43,"tag":274,"props":275,"children":276},"tr",{},[277,283],{"type":43,"tag":278,"props":279,"children":280},"th",{},[281],{"type":48,"value":282},"Task",{"type":43,"tag":278,"props":284,"children":285},{},[286],{"type":48,"value":287},"Load this file",{"type":43,"tag":289,"props":290,"children":291},"tbody",{},[292,310,327,344,361,378,395],{"type":43,"tag":274,"props":293,"children":294},{},[295,301],{"type":43,"tag":296,"props":297,"children":298},"td",{},[299],{"type":48,"value":300},"Defining conversation models",{"type":43,"tag":296,"props":302,"children":303},{},[304],{"type":43,"tag":87,"props":305,"children":307},{"className":306},[],[308],{"type":48,"value":309},"reference\u002Fdata-models.md",{"type":43,"tag":274,"props":311,"children":312},{},[313,318],{"type":43,"tag":296,"props":314,"children":315},{},[316],{"type":48,"value":317},"Setting up the module service",{"type":43,"tag":296,"props":319,"children":320},{},[321],{"type":43,"tag":87,"props":322,"children":324},{"className":323},[],[325],{"type":48,"value":326},"reference\u002Fservice.md",{"type":43,"tag":274,"props":328,"children":329},{},[330,335],{"type":43,"tag":296,"props":331,"children":332},{},[333],{"type":48,"value":334},"Configuring tools, prompt, streamText",{"type":43,"tag":296,"props":336,"children":337},{},[338],{"type":43,"tag":87,"props":339,"children":341},{"className":340},[],[342],{"type":48,"value":343},"reference\u002Fagent-setup.md",{"type":43,"tag":274,"props":345,"children":346},{},[347,352],{"type":43,"tag":296,"props":348,"children":349},{},[350],{"type":48,"value":351},"Building the POST chat endpoint",{"type":43,"tag":296,"props":353,"children":354},{},[355],{"type":43,"tag":87,"props":356,"children":358},{"className":357},[],[359],{"type":48,"value":360},"reference\u002Fapi-route.md",{"type":43,"tag":274,"props":362,"children":363},{},[364,369],{"type":43,"tag":296,"props":365,"children":366},{},[367],{"type":48,"value":368},"Implementing NDJSON streaming",{"type":43,"tag":296,"props":370,"children":371},{},[372],{"type":43,"tag":87,"props":373,"children":375},{"className":374},[],[376],{"type":48,"value":377},"reference\u002Fstreaming.md",{"type":43,"tag":274,"props":379,"children":380},{},[381,386],{"type":43,"tag":296,"props":382,"children":383},{},[384],{"type":48,"value":385},"Building the admin chat UI",{"type":43,"tag":296,"props":387,"children":388},{},[389],{"type":43,"tag":87,"props":390,"children":392},{"className":391},[],[393],{"type":48,"value":394},"reference\u002Fadmin-extension.md",{"type":43,"tag":274,"props":396,"children":397},{},[398,403],{"type":43,"tag":296,"props":399,"children":400},{},[401],{"type":48,"value":402},"Giving the agent code execution capability",{"type":43,"tag":296,"props":404,"children":405},{},[406],{"type":43,"tag":87,"props":407,"children":409},{"className":408},[],[410],{"type":48,"value":411},"reference\u002Fmedusa-exec.md",{"type":43,"tag":51,"props":413,"children":414},{},[415,420],{"type":43,"tag":57,"props":416,"children":417},{},[418],{"type":48,"value":419},"Minimum requirement:",{"type":48,"value":421}," Load at least the reference file matching your current task before writing code.",{"type":43,"tag":65,"props":423,"children":425},{"id":424},"related-skills",[426],{"type":48,"value":427},"Related Skills",{"type":43,"tag":51,"props":429,"children":430},{},[431],{"type":48,"value":432},"Load these alongside this skill when relevant:",{"type":43,"tag":72,"props":434,"children":435},{},[436,450],{"type":43,"tag":76,"props":437,"children":438},{},[439,448],{"type":43,"tag":57,"props":440,"children":441},{},[442],{"type":43,"tag":87,"props":443,"children":445},{"className":444},[],[446],{"type":48,"value":447},"building-with-medusa",{"type":48,"value":449}," — Medusa module patterns, workflows, data model conventions. Load when implementing the module service or custom backend logic.",{"type":43,"tag":76,"props":451,"children":452},{},[453,462],{"type":43,"tag":57,"props":454,"children":455},{},[456],{"type":43,"tag":87,"props":457,"children":459},{"className":458},[],[460],{"type":48,"value":461},"building-admin-dashboard-customizations",{"type":48,"value":463}," — Admin UI component patterns, TanStack Query, route registration. Load when building or extending the admin chat UI.",{"type":43,"tag":65,"props":465,"children":467},{"id":466},"architecture-overview",[468],{"type":48,"value":469},"Architecture Overview",{"type":43,"tag":471,"props":472,"children":476},"pre",{"className":473,"code":475,"language":48},[474],"language-text","src\u002Fmodules\u002Fagent\u002F\n  index.ts                ← Module() export + AGENT_MODULE constant\n  service.ts              ← MedusaService + Anthropic client + stream(messages, container, config)\n  models\u002F\n    session.ts            ← AgentSession (shared across all agents, filtered by agent_type)\n    message.ts            ← AgentMessage\n  agents\u002Findex.ts         ← streamText() orchestration\n  tools\u002F\n    medusa-exec.ts        ← MedusaExec tool (primary tool for all data operations)\n    todo-write.ts         ← TodoWrite tool\n  config\u002F\n    \u003Cagent-type>.ts       ← per-agent system prompt + tool descriptions\n\nsrc\u002Fapi\u002Fadmin\u002Fagent\u002F\u003Cagent-type>\u002F\n  route.ts                ← POST (AuthenticatedMedusaRequest, session lifecycle, NDJSON stream)\n  sessions\u002Froute.ts       ← GET session list (filtered by agent_type)\n  sessions\u002F[id]\u002Froute.ts  ← GET messages for a session\n\nsrc\u002Fadmin\u002Froutes\u002F\u003Cagent-type>\u002F\n  page.tsx                ← React chat UI (admin extension)\n\nsrc\u002Flib\u002Fcode-mode\u002F\n  executor.ts             ← sandboxed TypeScript executor used by MedusaExec\n",[477],{"type":43,"tag":87,"props":478,"children":480},{"__ignoreMap":479},"",[481],{"type":48,"value":475},{"type":43,"tag":65,"props":483,"children":485},{"id":484},"common-mistakes",[486],{"type":48,"value":487},"Common Mistakes",{"type":43,"tag":51,"props":489,"children":490},{},[491],{"type":48,"value":492},"Verify you are NOT doing these:",{"type":43,"tag":51,"props":494,"children":495},{},[496],{"type":43,"tag":57,"props":497,"children":498},{},[499],{"type":48,"value":500},"Security:",{"type":43,"tag":72,"props":502,"children":505},{"className":503},[504],"contains-task-list",[506,532],{"type":43,"tag":76,"props":507,"children":510},{"className":508},[509],"task-list-item",[511,517,519,525,527],{"type":43,"tag":512,"props":513,"children":516},"input",{"disabled":514,"type":515},true,"checkbox",[],{"type":48,"value":518}," Agent route uses ",{"type":43,"tag":87,"props":520,"children":522},{"className":521},[],[523],{"type":48,"value":524},"MedusaRequest",{"type":48,"value":526}," instead of ",{"type":43,"tag":87,"props":528,"children":530},{"className":529},[],[531],{"type":48,"value":110},{"type":43,"tag":76,"props":533,"children":535},{"className":534},[509],[536,539,541],{"type":43,"tag":512,"props":537,"children":538},{"disabled":514,"type":515},[],{"type":48,"value":540}," Agent route placed outside ",{"type":43,"tag":87,"props":542,"children":544},{"className":543},[],[545],{"type":48,"value":92},{"type":43,"tag":51,"props":547,"children":548},{},[549],{"type":43,"tag":57,"props":550,"children":551},{},[552],{"type":48,"value":553},"Architecture:",{"type":43,"tag":72,"props":555,"children":557},{"className":556},[504],[558,586,600],{"type":43,"tag":76,"props":559,"children":561},{"className":560},[509],[562,565,567,572,574,579,581],{"type":43,"tag":512,"props":563,"children":564},{"disabled":514,"type":515},[],{"type":48,"value":566}," Creating separate ",{"type":43,"tag":87,"props":568,"children":570},{"className":569},[],[571],{"type":48,"value":145},{"type":48,"value":573},"\u002F",{"type":43,"tag":87,"props":575,"children":577},{"className":576},[],[578],{"type":48,"value":153},{"type":48,"value":580}," models per agent instead of using ",{"type":43,"tag":87,"props":582,"children":584},{"className":583},[],[585],{"type":48,"value":161},{"type":43,"tag":76,"props":587,"children":589},{"className":588},[509],[590,593,595],{"type":43,"tag":512,"props":591,"children":592},{"disabled":514,"type":515},[],{"type":48,"value":594}," Importing services directly in tool files instead of resolving from ",{"type":43,"tag":87,"props":596,"children":598},{"className":597},[],[599],{"type":48,"value":185},{"type":43,"tag":76,"props":601,"children":603},{"className":602},[509],[604,607],{"type":43,"tag":512,"props":605,"children":606},{"disabled":514,"type":515},[],{"type":48,"value":608}," Building a custom tool for a data operation instead of using MedusaExec",{"type":43,"tag":51,"props":610,"children":611},{},[612],{"type":43,"tag":57,"props":613,"children":614},{},[615],{"type":48,"value":616},"Streaming:",{"type":43,"tag":72,"props":618,"children":620},{"className":619},[504],[621,638,661],{"type":43,"tag":76,"props":622,"children":624},{"className":623},[509],[625,628,630,636],{"type":43,"tag":512,"props":626,"children":627},{"disabled":514,"type":515},[],{"type":48,"value":629}," Missing ",{"type":43,"tag":87,"props":631,"children":633},{"className":632},[],[634],{"type":48,"value":635},"res.end()",{"type":48,"value":637}," after the stream loop (response never closes)",{"type":43,"tag":76,"props":639,"children":641},{"className":640},[509],[642,645,646,652,654,659],{"type":43,"tag":512,"props":643,"children":644},{"disabled":514,"type":515},[],{"type":48,"value":629},{"type":43,"tag":87,"props":647,"children":649},{"className":648},[],[650],{"type":48,"value":651},"Transfer-Encoding: chunked",{"type":48,"value":653}," or ",{"type":43,"tag":87,"props":655,"children":657},{"className":656},[],[658],{"type":48,"value":202},{"type":48,"value":660}," headers",{"type":43,"tag":76,"props":662,"children":664},{"className":663},[509],[665,668],{"type":43,"tag":512,"props":666,"children":667},{"disabled":514,"type":515},[],{"type":48,"value":669}," Not buffering incomplete lines on the client (JSON parse errors on split packets)",{"type":43,"tag":51,"props":671,"children":672},{},[673],{"type":43,"tag":57,"props":674,"children":675},{},[676],{"type":48,"value":677},"Module:",{"type":43,"tag":72,"props":679,"children":681},{"className":680},[504],[682,697,706],{"type":43,"tag":76,"props":683,"children":685},{"className":684},[509],[686,689,691],{"type":43,"tag":512,"props":687,"children":688},{"disabled":514,"type":515},[],{"type":48,"value":690}," Forgetting to register the module in ",{"type":43,"tag":87,"props":692,"children":694},{"className":693},[],[695],{"type":48,"value":696},"medusa-config.ts",{"type":43,"tag":76,"props":698,"children":700},{"className":699},[509],[701,704],{"type":43,"tag":512,"props":702,"children":703},{"disabled":514,"type":515},[],{"type":48,"value":705}," Forgetting to run migrations after changing models",{"type":43,"tag":76,"props":707,"children":709},{"className":708},[509],[710,713,715,720],{"type":43,"tag":512,"props":711,"children":712},{"disabled":514,"type":515},[],{"type":48,"value":714}," Hardcoding tool descriptions in ",{"type":43,"tag":87,"props":716,"children":718},{"className":717},[],[719],{"type":48,"value":246},{"type":48,"value":721}," instead of the config object",{"type":43,"tag":65,"props":723,"children":725},{"id":724},"reference-files-available",[726],{"type":48,"value":727},"Reference Files Available",{"type":43,"tag":471,"props":729,"children":732},{"className":730,"code":731,"language":48},[474],"reference\u002Fdata-models.md       - model.define(), agent_type discriminator, relationships, migrations\nreference\u002Fservice.md           - MedusaService extension, Anthropic init, stream(), module index, config registration\nreference\u002Fagent-setup.md       - streamText(), MedusaExec tool wiring, system prompt, context passing\nreference\u002Fapi-route.md         - POST route, session lifecycle, message persistence, streaming headers\nreference\u002Fstreaming.md         - NDJSON emission, fullStream iteration, chunk types, client-side parsing\nreference\u002Fadmin-extension.md   - React chat UI, streaming fetch, message rendering, tool call display, session sidebar\nreference\u002Fmedusa-exec.md       - Executor setup, MedusaExec tool, query.graph() patterns, error codes\n",[733],{"type":43,"tag":87,"props":734,"children":735},{"__ignoreMap":479},[736],{"type":48,"value":731},{"type":43,"tag":65,"props":738,"children":740},{"id":739},"testing",[741],{"type":48,"value":742},"Testing",{"type":43,"tag":51,"props":744,"children":745},{},[746],{"type":48,"value":747},"Once the agent is implemented, test it end-to-end directly in the admin dashboard:",{"type":43,"tag":749,"props":750,"children":751},"ol",{},[752,765,777,790,795,800],{"type":43,"tag":76,"props":753,"children":754},{},[755,757,763],{"type":48,"value":756},"Start the Medusa dev server (",{"type":43,"tag":87,"props":758,"children":760},{"className":759},[],[761],{"type":48,"value":762},"npx medusa develop",{"type":48,"value":764},")",{"type":43,"tag":76,"props":766,"children":767},{},[768,770,776],{"type":48,"value":769},"Open the admin dashboard and navigate to the agent's page in the sidebar (the label set in ",{"type":43,"tag":87,"props":771,"children":773},{"className":772},[],[774],{"type":48,"value":775},"defineRouteConfig",{"type":48,"value":764},{"type":43,"tag":76,"props":778,"children":779},{},[780,782,788],{"type":48,"value":781},"Type a simple read-only prompt — e.g. ",{"type":43,"tag":783,"props":784,"children":785},"em",{},[786],{"type":48,"value":787},"\"How many products are in the store?\"",{"type":48,"value":789}," — and submit",{"type":43,"tag":76,"props":791,"children":792},{},[793],{"type":48,"value":794},"Verify the response streams in and a new session appears in the sidebar",{"type":43,"tag":76,"props":796,"children":797},{},[798],{"type":48,"value":799},"Send a follow-up message in the same session to confirm conversation history is preserved",{"type":43,"tag":76,"props":801,"children":802},{},[803],{"type":48,"value":804},"Reload the page, select the session from the sidebar, and confirm the message history is restored from the database",{"type":43,"tag":51,"props":806,"children":807},{},[808],{"type":48,"value":809},"If anything is broken, check:",{"type":43,"tag":72,"props":811,"children":812},{},[813,825,845],{"type":43,"tag":76,"props":814,"children":815},{},[816,818,823],{"type":48,"value":817},"Browser network tab — the POST request should return ",{"type":43,"tag":87,"props":819,"children":821},{"className":820},[],[822],{"type":48,"value":202},{"type":48,"value":824}," with chunked lines",{"type":43,"tag":76,"props":826,"children":827},{},[828,830,836,837,843],{"type":48,"value":829},"Server logs — ",{"type":43,"tag":87,"props":831,"children":833},{"className":832},[],[834],{"type":48,"value":835},"[agent] tool_call",{"type":48,"value":147},{"type":43,"tag":87,"props":838,"children":840},{"className":839},[],[841],{"type":48,"value":842},"[agent] step_finish",{"type":48,"value":844}," lines confirm the agent is running",{"type":43,"tag":76,"props":846,"children":847},{},[848,850,856,857,863,865],{"type":48,"value":849},"Database — ",{"type":43,"tag":87,"props":851,"children":853},{"className":852},[],[854],{"type":48,"value":855},"agent_session",{"type":48,"value":147},{"type":43,"tag":87,"props":858,"children":860},{"className":859},[],[861],{"type":48,"value":862},"agent_message",{"type":48,"value":864}," tables should have rows with the correct ",{"type":43,"tag":87,"props":866,"children":868},{"className":867},[],[869],{"type":48,"value":161},{"items":871,"total":960},[872,888,904,916,922,937,947],{"slug":461,"name":461,"fn":873,"description":874,"org":875,"tags":876,"stars":21,"repoUrl":22,"updatedAt":887},"customize Medusa Admin dashboard UI","Load automatically when planning, researching, or implementing Medusa Admin dashboard UI (widgets, custom pages, forms, tables, data loading, navigation). REQUIRED for all admin UI work in ALL modes (planning, implementation, exploration). Contains design patterns, component usage, and data loading patterns that MCP servers don't provide.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[877,880,883,884],{"name":878,"slug":879,"type":16},"E-commerce","e-commerce",{"name":881,"slug":882,"type":16},"Frontend","frontend",{"name":9,"slug":8,"type":16},{"name":885,"slug":886,"type":16},"UI Components","ui-components","2026-04-06T18:29:57.203659",{"slug":889,"name":889,"fn":890,"description":891,"org":892,"tags":893,"stars":21,"repoUrl":22,"updatedAt":903},"building-storefronts","implement Medusa storefront features","Load automatically when planning, researching, or implementing Medusa storefront features (calling custom API routes, SDK integration, React Query patterns, data fetching). REQUIRED for all storefront development in ALL modes (planning, implementation, exploration). Contains SDK usage patterns, frontend integration, and critical rules for calling Medusa APIs.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[894,895,898,899,900],{"name":878,"slug":879,"type":16},{"name":896,"slug":897,"type":16},"Engineering","engineering",{"name":881,"slug":882,"type":16},{"name":9,"slug":8,"type":16},{"name":901,"slug":902,"type":16},"React","react","2026-04-06T18:29:55.957429",{"slug":447,"name":447,"fn":905,"description":906,"org":907,"tags":908,"stars":21,"repoUrl":22,"updatedAt":915},"implement Medusa backend features","Load automatically when planning, researching, or implementing ANY Medusa backend features (custom modules, API routes, workflows, data models, module links, business logic). REQUIRED for all Medusa backend work in ALL modes (planning, implementation, exploration). Contains architectural patterns, best practices, and critical rules that MCP servers don't provide.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[909,910,913,914],{"name":14,"slug":15,"type":16},{"name":911,"slug":912,"type":16},"Data Modeling","data-modeling",{"name":878,"slug":879,"type":16},{"name":9,"slug":8,"type":16},"2026-04-06T18:29:54.652389",{"slug":4,"name":4,"fn":5,"description":6,"org":917,"tags":918,"stars":21,"repoUrl":22,"updatedAt":23},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[919,920,921],{"name":19,"slug":20,"type":16},{"name":14,"slug":15,"type":16},{"name":9,"slug":8,"type":16},{"slug":923,"name":923,"fn":924,"description":925,"org":926,"tags":927,"stars":21,"repoUrl":22,"updatedAt":936},"db-generate","generate database migrations for Medusa modules","Generate database migrations for a Medusa module",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[928,929,932,933],{"name":14,"slug":15,"type":16},{"name":930,"slug":931,"type":16},"Database","database",{"name":9,"slug":8,"type":16},{"name":934,"slug":935,"type":16},"Migration","migration","2026-04-06T18:29:53.415671",{"slug":938,"name":938,"fn":939,"description":940,"org":941,"tags":942,"stars":21,"repoUrl":22,"updatedAt":946},"db-migrate","run database migrations in Medusa","Run database migrations in Medusa",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[943,944,945],{"name":930,"slug":931,"type":16},{"name":9,"slug":8,"type":16},{"name":934,"slug":935,"type":16},"2026-04-06T18:29:52.187377",{"slug":948,"name":948,"fn":949,"description":950,"org":951,"tags":952,"stars":21,"repoUrl":22,"updatedAt":959},"learning-medusa","guide Medusa development learning","Load automatically when user asks to learn Medusa development (e.g., \"teach me how to build with medusa\", \"guide me through medusa\", \"I want to learn medusa\"). Interactive guided tutorial where Claude acts as a coding bootcamp instructor, teaching step-by-step with checkpoints and verification.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[953,954,955,956],{"name":14,"slug":15,"type":16},{"name":878,"slug":879,"type":16},{"name":9,"slug":8,"type":16},{"name":957,"slug":958,"type":16},"Templates","templates","2026-04-06T18:29:58.461689",17,{"items":962,"total":960},[963,970,978,985,991,998,1004,1011,1028,1040,1053,1066],{"slug":461,"name":461,"fn":873,"description":874,"org":964,"tags":965,"stars":21,"repoUrl":22,"updatedAt":887},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[966,967,968,969],{"name":878,"slug":879,"type":16},{"name":881,"slug":882,"type":16},{"name":9,"slug":8,"type":16},{"name":885,"slug":886,"type":16},{"slug":889,"name":889,"fn":890,"description":891,"org":971,"tags":972,"stars":21,"repoUrl":22,"updatedAt":903},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[973,974,975,976,977],{"name":878,"slug":879,"type":16},{"name":896,"slug":897,"type":16},{"name":881,"slug":882,"type":16},{"name":9,"slug":8,"type":16},{"name":901,"slug":902,"type":16},{"slug":447,"name":447,"fn":905,"description":906,"org":979,"tags":980,"stars":21,"repoUrl":22,"updatedAt":915},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[981,982,983,984],{"name":14,"slug":15,"type":16},{"name":911,"slug":912,"type":16},{"name":878,"slug":879,"type":16},{"name":9,"slug":8,"type":16},{"slug":4,"name":4,"fn":5,"description":6,"org":986,"tags":987,"stars":21,"repoUrl":22,"updatedAt":23},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[988,989,990],{"name":19,"slug":20,"type":16},{"name":14,"slug":15,"type":16},{"name":9,"slug":8,"type":16},{"slug":923,"name":923,"fn":924,"description":925,"org":992,"tags":993,"stars":21,"repoUrl":22,"updatedAt":936},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[994,995,996,997],{"name":14,"slug":15,"type":16},{"name":930,"slug":931,"type":16},{"name":9,"slug":8,"type":16},{"name":934,"slug":935,"type":16},{"slug":938,"name":938,"fn":939,"description":940,"org":999,"tags":1000,"stars":21,"repoUrl":22,"updatedAt":946},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1001,1002,1003],{"name":930,"slug":931,"type":16},{"name":9,"slug":8,"type":16},{"name":934,"slug":935,"type":16},{"slug":948,"name":948,"fn":949,"description":950,"org":1005,"tags":1006,"stars":21,"repoUrl":22,"updatedAt":959},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1007,1008,1009,1010],{"name":14,"slug":15,"type":16},{"name":878,"slug":879,"type":16},{"name":9,"slug":8,"type":16},{"name":957,"slug":958,"type":16},{"slug":1012,"name":1012,"fn":1013,"description":1014,"org":1015,"tags":1016,"stars":21,"repoUrl":22,"updatedAt":1027},"mcloud-deployments","manage Medusa Cloud deployments","Execute mcloud deployments commands to list deployments, retrieve deployment details, and fetch build logs. Use when listing deployments, checking deployment status, or reading build output for debugging build failures.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1017,1020,1023,1024],{"name":1018,"slug":1019,"type":16},"Deployment","deployment",{"name":1021,"slug":1022,"type":16},"Logs","logs",{"name":9,"slug":8,"type":16},{"name":1025,"slug":1026,"type":16},"Observability","observability","2026-05-09T05:40:51.727369",{"slug":1029,"name":1029,"fn":1030,"description":1031,"org":1032,"tags":1033,"stars":21,"repoUrl":22,"updatedAt":1039},"mcloud-environments","manage Medusa Cloud environments","Execute mcloud environments commands to list, get, create, delete, redeploy, or trigger builds for Cloud environments. Use when managing environment lifecycle, redeploying after variable changes, or starting new builds from source.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1034,1035,1036],{"name":1018,"slug":1019,"type":16},{"name":9,"slug":8,"type":16},{"name":1037,"slug":1038,"type":16},"Operations","operations","2026-07-17T05:31:36.384292",{"slug":1041,"name":1041,"fn":1042,"description":1043,"org":1044,"tags":1045,"stars":21,"repoUrl":22,"updatedAt":1052},"mcloud-local","reproduce Cloud builds locally","Execute mcloud local build to reproduce a Cloud build on the local machine. Use when debugging a build-failed deployment without pushing to the tracked branch, iterating on a build fix, or testing build-variable changes locally. Requires Docker and must run inside the project's Git repo.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1046,1049,1050,1051],{"name":1047,"slug":1048,"type":16},"Debugging","debugging",{"name":1018,"slug":1019,"type":16},{"name":896,"slug":897,"type":16},{"name":9,"slug":8,"type":16},"2026-07-17T06:05:07.199529",{"slug":1054,"name":1054,"fn":1055,"description":1056,"org":1057,"tags":1058,"stars":21,"repoUrl":22,"updatedAt":1065},"mcloud-logs","fetch and stream runtime cloud logs","Execute mcloud logs to fetch and stream runtime logs for Cloud environments. Use when reading backend or storefront logs, filtering by time range, searching for errors, or scoping logs to a specific deployment.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1059,1062,1063,1064],{"name":1060,"slug":1061,"type":16},"Cloud","cloud",{"name":1021,"slug":1022,"type":16},{"name":9,"slug":8,"type":16},{"name":1025,"slug":1026,"type":16},"2026-05-09T05:40:46.707854",{"slug":1067,"name":1067,"fn":1068,"description":1069,"org":1070,"tags":1071,"stars":21,"repoUrl":22,"updatedAt":1074},"mcloud-organizations","manage Medusa Cloud organizations","Execute mcloud organizations commands to list or get Cloud organizations. Use when discovering organizations, resolving organization IDs by name, or retrieving organization details including members and subscription.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1072,1073],{"name":9,"slug":8,"type":16},{"name":1037,"slug":1038,"type":16},"2026-05-09T05:40:54.327722"]