Agent skill · software engineering · medusajs
creating-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).
Why this skill is useful
Adds detailed architecture and executable TypeScript patterns for building internal admin-facing AI agents in Medusa, which are not covered in public documentation.
What it needs
Requires medusa installed locally. About 4k tokens when loaded. Last updated 2026-08-06. 207 stars on the source repository.
What this skill does
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 agenttype to distinguish sessions per agent. Never create separate models per agent. Pass MedusaContainer via experimentalcontext — 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. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills medusajs/creating-internal-agents