creating-internal-agents

Name: creating-internal-agents
Author: medusajs

202stars24forks

How to install creating-internal-agents?

medusajs/medusa-agent-skills/creating-internal-agents

$npx -y skills add medusajs/medusa-agent-skills --skill creating-internal-agents

Installs into the current project.

Summary

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 c

Files · 1

View on GitHub

SKILL.md

1	# Creating Agents in Medusa
2
3	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.
4
5	## Constraints
6
7	- 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.
8	- 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.
9	- 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).
10	- 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.
11	- Pass `MedusaContainer` via `experimental_context` — never import services directly in tool files; that causes circular dependencies.
12	- Stream format is NDJSON — `Content-Type: application/x-ndjson`, one JSON object per line followed by `\n`.
13	- Run migrations after adding or changing models (`npx medusa db:generate agent && npx medusa db:migrate`).
14	- Tool descriptions live in config, not inline in `tool()` — the config object overrides them at runtime.
15
16	## CRITICAL: Load Reference Files When Needed
17
18	⚠️ The quick reference below is NOT sufficient for implementation. Load the relevant reference file before writing any code.
19
20	\| Task \| Load this file \|
21	\|------\|---------------\|
22	\| Defining conversation models \| `reference/data-models.md` \|
23	\| Setting up the module service \| `reference/service.md` \|
24	\| Configuring tools, prompt, streamText \| `reference/agent-setup.md` \|
25	\| Building the POST chat endpoint \| `reference/api-route.md` \|
26	\| Implementing NDJSON streaming \| `reference/streaming.md` \|
27	\| Building the admin chat UI \| `reference/admin-extension.md` \|
28	\| Giving the agent code execution capability \| `reference/medusa-exec.md` \|
29
30	Minimum requirement: Load at least the reference file matching your current task before writing code.
31
32	## Related Skills
33
34	Load these alongside this skill when relevant:
35
36	- `building-with-medusa` — Medusa module patterns, workflows, data model conventions. Load when implementing the module service or custom backend logic.
37	- `building-admin-dashboard-customizations` — Admin UI component patterns, TanStack Query, route registration. Load when building or extending the admin chat UI.
38
39	## Architecture Overview
40
41	```
42	src/modules/agent/
43	index.ts ← Module() export + AGENT_MODULE constant
44	service.ts ← MedusaService + Anthropic client + stream(messages, container, config)
45	models/
46	session.ts ← AgentSession (shared across all agents, filtered by agent_type)
47	message.ts ← AgentMessage
48	agents/index.ts ← streamText() orchestration
49	tools/
50	medusa-exec.ts ← MedusaExec tool (primary tool for all data operations)
51	todo-write.ts ← TodoWrite tool
52	config/
53	<agent-type>.ts ← per-agent system prompt + tool descriptions
54
55	src/api/admin/agent/<agent-type>/
56	route.ts ← POST (AuthenticatedMedusaRequest, session lifecycle, NDJSON stream)
57	sessions/route.ts ← GET session list (filtered by agent_type)
58	sessions/[id]/route.ts ← GET messages for a session
59
60	src/admin/routes/<agent-type>/
61	page.tsx ← React chat UI (admin extension)
62
63	src/lib/code-mode/
64	executor.ts ← sandboxed TypeScript executor used by MedusaExec
65	```
66
67	## Common Mistakes
68
69	Verify you are NOT doing these:
70
71	Security:
72	- [ ] Agent route uses `MedusaRequest` instead of `AuthenticatedMedusaRequest`
73	- [ ] Agent route placed outside `src/api/admin/`
74
75	Architecture:
76	- [ ] Creating separate `AgentSession`/`AgentMessage` models per

People who liked this also viewed

6 picks

Type

creating-internal-agents

202stars24forks

View on GitHub

How to install creating-internal-agents?

medusajs/medusa-agent-skills/creating-internal-agents

$npx -y skills add medusajs/medusa-agent-skills --skill creating-internal-agents

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Creating Agents in Medusa
2
3	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.
4
5	## Constraints
6
7	- 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.
8	- 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.
9	- 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).
10	- 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.
11	- Pass `MedusaContainer` via `experimental_context` — never import services directly in tool files; that causes circular dependencies.
12	- Stream format is NDJSON — `Content-Type: application/x-ndjson`, one JSON object per line followed by `\n`.
13	- Run migrations after adding or changing models (`npx medusa db:generate agent && npx medusa db:migrate`).
14	- Tool descriptions live in config, not inline in `tool()` — the config object overrides them at runtime.
15
16	## CRITICAL: Load Reference Files When Needed
17
18	⚠️ The quick reference below is NOT sufficient for implementation. Load the relevant reference file before writing any code.
19
20	\| Task \| Load this file \|
21	\|------\|---------------\|
22	\| Defining conversation models \| `reference/data-models.md` \|
23	\| Setting up the module service \| `reference/service.md` \|
24	\| Configuring tools, prompt, streamText \| `reference/agent-setup.md` \|
25	\| Building the POST chat endpoint \| `reference/api-route.md` \|
26	\| Implementing NDJSON streaming \| `reference/streaming.md` \|
27	\| Building the admin chat UI \| `reference/admin-extension.md` \|
28	\| Giving the agent code execution capability \| `reference/medusa-exec.md` \|
29
30	Minimum requirement: Load at least the reference file matching your current task before writing code.
31
32	## Related Skills
33
34	Load these alongside this skill when relevant:
35
36	- `building-with-medusa` — Medusa module patterns, workflows, data model conventions. Load when implementing the module service or custom backend logic.
37	- `building-admin-dashboard-customizations` — Admin UI component patterns, TanStack Query, route registration. Load when building or extending the admin chat UI.
38
39	## Architecture Overview
40
41	```
42	src/modules/agent/
43	index.ts ← Module() export + AGENT_MODULE constant
44	service.ts ← MedusaService + Anthropic client + stream(messages, container, config)
45	models/
46	session.ts ← AgentSession (shared across all agents, filtered by agent_type)
47	message.ts ← AgentMessage
48	agents/index.ts ← streamText() orchestration
49	tools/
50	medusa-exec.ts ← MedusaExec tool (primary tool for all data operations)
51	todo-write.ts ← TodoWrite tool
52	config/
53	<agent-type>.ts ← per-agent system prompt + tool descriptions
54
55	src/api/admin/agent/<agent-type>/
56	route.ts ← POST (AuthenticatedMedusaRequest, session lifecycle, NDJSON stream)
57	sessions/route.ts ← GET session list (filtered by agent_type)
58	sessions/[id]/route.ts ← GET messages for a session
59
60	src/admin/routes/<agent-type>/
61	page.tsx ← React chat UI (admin extension)
62
63	src/lib/code-mode/
64	executor.ts ← sandboxed TypeScript executor used by MedusaExec
65	```
66
67	## Common Mistakes
68
69	Verify you are NOT doing these:
70
71	Security:
72	- [ ] Agent route uses `MedusaRequest` instead of `AuthenticatedMedusaRequest`
73	- [ ] Agent route placed outside `src/api/admin/`
74
75	Architecture:
76	- [ ] Creating separate `AgentSession`/`AgentMessage` models per

People who liked this also viewed

6 picks

Type