creating-agents-in-medusa

在 Medusa 中创建 Agent

本技能涵盖为 Medusa 项目添加内部管理端 AI Agent所需的完整技术栈。这些 Agent 供商家和门店运营人员通过 Medusa 管理后台使用，不面向店铺前台的顾客。面向顾客的 Agent（例如店铺前台聊天机器人）需要采用不同的架构：公开 API 路由、不使用 MedusaExec，并使用店铺前台身份验证。

约束

• 仅限内部使用——此架构面向管理端用户（商家、运营人员、支持人员），不面向顾客。路由位于 src/api/admin/ 下，界面位于 Medusa 管理后台中，且全程由管理端身份验证控制访问。
• 身份验证不可妥协——MedusaExec 会运行拥有完整数据库访问权限的任意 TypeScript。所有 Agent 路由都必须使用 AuthenticatedMedusaRequest，并位于 src/api/admin/ 下。未经身份验证的端点会造成远程代码执行漏洞。
• 使用 MedusaExec，而非自定义工具——对于任何数据操作，Agent 都应编写 TypeScript，并通过 MedusaExec 执行。只有无法用可执行的 TypeScript 表达的功能（例如使用密钥调用外部 API）才应构建自定义工具。
• 一个共享模块，多个 Agent——AgentSession 和 AgentMessage 是共享基础设施。使用 agent_type 区分不同 Agent 的会话。切勿为每个 Agent 单独创建模型。
• 通过 experimental_context 传递 MedusaContainer——切勿在工具文件中直接导入服务，否则会导致循环依赖。
• 流格式为 NDJSON——Content-Type: application/x-ndjson，每行一个 JSON 对象，并以 \n 结尾。
• 添加或修改模型后运行迁移（npx medusa db:generate agent && npx medusa db:migrate）。
• 工具描述应放在配置中，而非内联写在 tool() 中——配置对象会在运行时覆盖工具描述。

重要：按需加载参考文件

**⚠️ 以下快速参考不足以支持实现。**编写代码前，请加载相关参考文件。

任务	加载此文件
定义对话模型	reference/data-models.md
设置模块服务	reference/service.md
配置工具、提示词和 streamText	reference/agent-setup.md
构建 POST 聊天端点	reference/api-route.md
实现 NDJSON 流式传输	reference/streaming.md
构建管理端聊天 UI	reference/admin-extension.md
赋予 Agent 代码执行能力	reference/medusa-exec.md

**最低要求：**编写代码前，至少加载与当前任务对应的参考文件。

相关技能

在适用时，结合此技能加载以下技能：

• building-with-medusa——Medusa 模块模式、工作流和数据模型约定。实现模块服务或自定义后端逻辑时加载。
• building-admin-dashboard-customizations——管理端 UI 组件模式、TanStack Query 和路由注册。构建或扩展管理端聊天 UI 时加载。

架构概览

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

常见错误

确认你没有犯以下错误：

安全性：

• Agent 路由使用了 MedusaRequest，而不是 AuthenticatedMedusaRequest
• Agent 路由被放在 src/api/admin/ 之外

架构：

• 为每个 Agent 创建单独的 AgentSession/AgentMessage 模型，而不是使用 agent_type
• 在工具文件中直接导入服务，而不是通过 experimental_context 解析服务
• 为数据操作构建自定义工具，而不是使用 MedusaExec

流式传输：

• 流循环结束后缺少 res.end()（响应永远不会关闭）
• 缺少 Transfer-Encoding: chunked 或 Content-Type: application/x-ndjson 请求头
• 客户端没有缓冲不完整的行（拆分的数据包会导致 JSON 解析错误）

模块：

• 忘记在 medusa-config.ts 中注册模块
• 更改模型后忘记运行迁移
• 在 tool() 中硬编码工具描述，而不是放在配置对象中

可用的参考文件

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 tool wiring, system prompt, context passing
reference/api-route.md         - POST route, session lifecycle, message persistence, streaming headers
reference/streaming.md         - NDJSON emission, fullStream iteration, chunk types, client-side parsing
reference/admin-extension.md   - React chat UI, streaming fetch, message rendering, tool call display, session sidebar
reference/medusa-exec.md       - Executor setup, MedusaExec tool, query.graph() patterns, error codes

测试

Agent 实现完成后，直接在管理后台进行端到端测试：

1. 启动 Medusa 开发服务器（npx medusa develop）
2. 打开管理后台，点击侧边栏中的 Agent 页面（defineRouteConfig 中设置的标签）
3. 输入一个简单的只读提示词，例如 “店铺中有多少件商品？”，然后提交
4. 确认响应以流式方式传入，并且侧边栏中出现一个新会话
5. 在同一会话中发送后续消息，确认对话历史得以保留
6. 重新加载页面，从侧边栏选择该会话，并确认消息历史已从数据库恢复

如果有任何问题，请检查：

• 浏览器网络选项卡 — POST 请求应返回 Content-Type: application/x-ndjson，并包含分块的行
• 服务器日志 — [agent] tool_call 和 [agent] step_finish 日志行可确认 Agent 正在运行
• 数据库 — agent_session 和 agent_message 表应包含 agent_type 正确的记录