creating-agents-in-medusa

用途

本技能面向在 Medusa 项目中添加内部、面向管理员（admin-facing）AI 智能体的完整技术栈。这类智能体由商家与店铺运营人员通过 Medusa 管理后台使用，并非面向店铺前台的顾客。若需要面向顾客的智能体（例如店铺前台聊天机器人），则需要另一套架构：公开 API 路由、不使用 MedusaExec，并采用前台鉴权方式。

核心约束

仅限内部使用：该架构面向管理员用户（商家、运营人员、支持人员），不面向顾客。路由位于 src/api/admin/ 下，UI 位于 Medusa 管理后台，全程由管理员鉴权保护访问。
鉴权不可妥协：MedusaExec 会执行具有完整数据库访问权限的任意 TypeScript。所有智能体路由必须使用 AuthenticatedMedusaRequest，并位于 src/api/admin/ 下。未鉴权的端点将构成远程代码执行漏洞。
使用 MedusaExec，而非自定义工具：任何数据操作都由智能体编写 TypeScript 并通过 MedusaExec 执行。只有当某项能力无法用可执行 TypeScript 表达时（例如使用密钥调用外部 API），才构建自定义工具。
一个共享模块，多个智能体：AgentSession 与 AgentMessage 属于共享基础设施。使用 agent_type 区分各智能体的会话。切勿为每个智能体创建独立的模型。
通过 experimental_context 传递 MedusaContainer：切勿在工具文件中直接导入服务，否则会导致循环依赖。
流格式为 NDJSON：Content-Type: application/x-ndjson，每行一个 JSON 对象，后跟 \n。
在添加或更改模型后运行迁移（npx medusa db:generate agent && npx medusa db:migrate）。
工具描述位于 config 中，而非内联在 tool() 里——config 对象会在运行时覆盖它们。

关键提示：按需加载参考文件

下方快速参考不足以直接用于实现。在编写任何代码之前，请加载与当前任务相关的参考文件：

定义会话模型 → 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
为智能体赋予代码执行能力 → reference/medusa-exec.md

最低要求：在编写代码之前，至少加载与当前任务相匹配的参考文件。

架构概览

src/modules/agent/
  index.ts                ← Module() 导出 + AGENT_MODULE 常量
  service.ts              ← MedusaService + Anthropic 客户端 + stream(messages, container, config)
  models/
    session.ts            ← AgentSession（所有智能体共享，按 agent_type 过滤）
    message.ts            ← AgentMessage
  agents/index.ts         ← streamText() 编排
  tools/
    medusa-exec.ts        ← MedusaExec 工具（所有数据操作的主要工具）
    todo-write.ts         ← TodoWrite 工具
  config/
    <agent-type>.ts       ← 每个智能体的系统提示词 + 工具描述

src/api/admin/agent/<agent-type>/
  route.ts                ← POST（AuthenticatedMedusaRequest、会话生命周期、NDJSON 流）
  sessions/route.ts       ← GET 会话列表（按 agent_type 过滤）
  sessions/[id]/route.ts  ← GET 某个会话的消息

src/admin/routes/<agent-type>/
  page.tsx                ← React 聊天 UI（管理扩展）

src/lib/code-mode/
  executor.ts             ← MedusaExec 使用的沙箱 TypeScript 执行器

常见错误

请确认自己没有犯以下错误：

安全：

智能体路由使用 MedusaRequest 而非 AuthenticatedMedusaRequest
智能体路由放置在 src/api/admin/ 之外

架构：

为每个智能体创建独立的 AgentSession/AgentMessage 模型，而非使用 agent_type
在工具文件中直接导入服务，而非从 experimental_context 解析
为数据操作构建自定义工具，而非使用 MedusaExec

流式传输：

流循环后缺少 res.end()（响应永不关闭）
缺少 Transfer-Encoding: chunked 或 Content-Type: application/x-ndjson 头
客户端未缓冲不完整的行（分包时出现 JSON 解析错误）

模块：

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

可用的参考文件

reference/data-models.md —— model.define()、agent_type 判别字段、关系、迁移
reference/service.md —— MedusaService 扩展、Anthropic 初始化、stream()、模块索引、配置注册
reference/agent-setup.md —— streamText()、MedusaExec 工具接线、系统提示词、上下文传递
reference/api-route.md —— POST 路由、会话生命周期、消息持久化、流式头
reference/streaming.md —— NDJSON 发送、fullStream 迭代、chunk 类型、客户端解析
reference/admin-extension.md —— React 聊天 UI、流式 fetch、消息渲染、工具调用展示、会话侧边栏
reference/medusa-exec.md —— 执行器设置、MedusaExec 工具、query.graph() 模式、错误码

测试

智能体实现完成后，可直接在管理后台进行端到端测试：

启动 Medusa 开发服务器（npx medusa develop）
打开管理后台，在侧边栏导航到该智能体页面（即 defineRouteConfig 中设置的标签）
输入一个简单的只读提示词——例如“How many products are in the store?”——并提交
验证响应以流式返回，且侧边栏出现新会话
在同一会话中发送后续消息，确认对话历史被保留
重新加载页面，从侧边栏选择该会话，确认消息历史从数据库恢复

若出现问题，请检查：

浏览器网络面板——POST 请求应返回 Content-Type: application/x-ndjson 且带有分块行
服务器日志——[agent] tool_call 与 [agent] step_finish 行确认智能体正在运行
数据库——agent_session 与 agent_message 表中应有带正确 agent_type 的行

技能介绍

用途