如何用Open Mercato AI Playground调试智能体Playground完整指南【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercatoOpen Mercato 是一款面向 CRM/ERP 与商务场景的开源 AI 工程基础框架其内置的AI Playground是调试智能体AI Agent最快的沙盒无需搭建任何宿主页面你就能端到端地运行、对话、检查工具调用和提示词覆盖效果。本文将用零基础友好的方式带你走完 Playground 的完整使用流程打开入口、选择智能体、跑通聊天与结构化输出两种模式并读懂调试面板里的每一处细节。一、什么是 Open Mercato AI PlaygroundAI Playground 是一个交互式调试页面它会列出当前应用里所有已注册的 AI 智能体让你直接在浏览器里验证智能体能否正常响应模型、Provider 是否配置正确工具白名单allowed tools是否按预期生效租户级提示词覆盖prompt override是否即时生效无需重启智能体循环agentic loop每一步使用了哪个模型、调用了哪些工具、为什么停止页面由 AiPlaygroundPageClient.tsx 实现官方文档见 playground.mdx。二、快速打开 Playground入口与权限Playground 的访问路径固定为/backend/config/ai-assistant/playground唯一前提当前用户需要具备ai_assistant.settings.manage特性feature。这个权限在 page.meta.ts 中声明——如果你打开页面看不到内容先确认角色是否被授予了该特性。三、选择智能体一张信息卡片看懂全部配置进入页面后顶部的Agent 选择器会列出所有聚合进ai-agents.generated.ts的智能体。选中某个智能体后信息卡片会立刻显示它的关键配置字段含义Module智能体所属模块如customersExecution modechat默认对话模式或object结构化输出模式Mutation policy写操作策略如read-onlyAllowed tools该智能体可用的工具数量选择器还会驱动调试面板中显示的系统提示词、工具白名单和变更策略所以换智能体后请留意面板内容是否同步更新。卡片下方还有Model Resolution 面板显示本次会话实际解析出的 Provider、模型 ID、Base URL 和来源如env_default、allowlist_fallback。这是排查到底哪个模型在干活的第一步。四、Chat 模式像聊天一样调试智能体当智能体声明executionMode: chat默认值时Playground 会渲染一个完整的AiChat实例并预注册了四张变更审批卡片mutation preview、field diff、confirmation、result。直接输入问题发送即可。几个实用细节任务计划Task Plan如果智能体开启了taskPlan: { enabled: true }你会在原始工具调用行之上看到实时的任务清单步骤会从pending→running→done推进附件上传若智能体的acceptedMediaTypes非空输入框旁会出现内联附件上传器会话隔离每个会话拥有稳定的conversationId重复请求会被幂等去重官方推荐的冒烟测试可直接照做选择customers.account_assistant或customers.deal_analyzer提问Find deals assigned to Joe and summarize the useful matches.验证任务计划先于工具结果出现、对应步骤走到done、且内部meta.update_task_plan行不会暴露给操作者五、Object 模式预览结构化输出切换到Object mode标签页聊天框会变成 JSON 输入编辑器 结果面板适合调试executionMode: object的智能体例如 catalog 模块 中的商品属性抽取器。运行后运行时会自动用agent.output.schema校验返回对象违规项会内联标出结果区还会展示 finish reason 与输入/输出 token 用量展开 Last request payload 可看到实际发出的请求体方便复现问题⚠️ 注意chat 类智能体切到 Object 标签会显示模式不可用提示反之亦然——这是正常行为请选中匹配模式的智能体。六、调试面板读懂每一处细节打开右上角的Debug panel开关后面板会展示调度器为当前会话做出的完整解析结果这正是 Playground 的杀手锏面板内容你能确认什么Model id Provider id实际生效的模型含覆盖来源Resolved tool list工具名、isMutation标记、requiredFeatures验证白名单Prompt section map每个提示词分节的来源default/override/placeholderTool call result log实时流式展示每次工具调用与结果Loop trace最近一轮每一步的模型、工具调用、repairToolCall修复尝试、总 token 和停止原因Loop trace 的停止原因取值包括stepCountIs、hasToolCall、loop_budget_exceeded、finish-reason:stop|tool-calls|length、aborted——排查智能体为什么中途停下时全靠它。典型用法在 Agent Settings 页面 保存新的提示词覆盖后无需重启任何服务直接回到 Playground 发一条消息就能通过 Prompt section map 确认覆盖已送达运行时。另外如果租户在设置中打开了Disable agentic loop急停开关Playground 会在输入框上方显示LoopDisabledBanner此时智能体会被折叠为单次模型调用——若你看到循环突然没了先检查这里。七、Playground vs 页面内嵌 何时用哪个场景推荐编写智能体、迭代提示词覆盖、QA 工具白名单✅ Playground真实用户流程依赖页面上下文的智能体✅ 页面内嵌AiChat原因很简单Playground不会传入真实的pageContext依赖resolvePageContext的智能体在 Playground 里会看到空白上下文。所以最终验收仍需在目标页面完成。八、键盘快捷键与常见问题排查快捷键与全局AiChat保持一致快捷键动作Cmd/Ctrl Enter发送消息Object 模式下提交 JSONEscape中止进行中的请求Shift Enter换行遇到异常时对照 developer-guide.mdx 的常见陷阱表现象可能原因解决智能体不出现在 Playground没跑yarn generate或文件不在模块根目录移到根目录后重新生成调度器返回 403requiredFeatures不在用户 ACL 中补进acl.ts并在setup.ts授权刷新结构缓存工具对模型隐身不在allowedTools中或工具名拼错显式加入白名单名称区分大小写no_provider_configured未配置任何 Provider 环境变量配置ANTHROPIC_API_KEY/OPENAI_API_KEY等九、参考资料Playground 官方文档apps/docs/docs/framework/ai-assistant/playground.mdx页面实现AiPlaygroundPageClient.tsx智能体契约与示例agents.mdx、customers/ai-agents.ts提示词/策略覆盖settings.mdxAI 框架总览overview.mdx掌握以上流程后你的智能体调优闭环就完整了改配置 → Playground 验证 → 页面内嵌验收。【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercato创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考