creating-agents-in-medusa

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.