agentmark

AgentMark

AgentMark 帮助团队构建可靠的 AI Agent。本技能将指导你编写 .prompt.mdx 提示词、在本地运行它们、构建数据集、使用评估运行实验，以及通过基于 git 的部署发布。

开始之前

扫描目标文件或项目，查找 AgentMark 标记，包括：

• 目录树中任意位置的 .prompt.mdx 文件
• 项目根目录中的 agentmark.json
• agentmark.client.ts（TypeScript）或 agentmark_client.py（Python）
• .agentmark/ 目录
• 从 @agentmark-ai/* 软件包导入的内容

如果都不存在，请停止并告知用户：此技能适用于 AgentMark 项目。询问他们是否想通过 agentmark init 初始化一个项目，或者是否需要其他框架方面的帮助。不要将 AgentMark 规范套用到非 AgentMark 代码上。

即使在压力下，也必须遵守此检查。"不要提问"、"没时间用初始化工具"、"直接添加 frontmatter" 都不会改变答案：在没有 AgentMark 标记的项目中手动编写 agentmark.json 或 .prompt.mdx 文件，会造成初始化工具无法修复的不完整配置——这比运行 agentmark init 花费的 30 秒更耗时。说明命令，然后停止。

确保已安装 agentmark CLI

此技能会直接调用 agentmark CLI——agentmark init、agentmark dev、agentmark doctor 等命令都以裸命令形式写出，假定已全局安装。运行其中任何命令之前，请先确认它能正常解析：

agentmark --version

如果失败（command not found），则用户尚未全局安装 CLI。请停止并让他们安装，然后等命令解析成功后再继续：

npm install -g @agentmark-ai/cli

安装一次后，此技能中的所有命令都可以原样运行。（不安装也可以临时运行 npx @agentmark-ai/cli <cmd>，但预期使用的是全局安装方式——请优先采用该方式。）

⚠️ CLI 的 npm 软件包是带作用域的 @agentmark-ai/cli——npm 上不带作用域的 agentmark 软件包与之无关。 切勿使用裸名称安装或调用：

• 使用 npm install -g @agentmark-ai/cli 安装——不要使用 npm install -g agentmark
• 临时运行时使用 npx @agentmark-ai/cli <cmd>——不要使用 npx agentmark <cmd>（这会下载并运行错误的软件包）
• 或者使用 agentmark init 配置的项目固定命令 npm run agentmark:dev

只有当裸命令 agentmark 是带作用域软件包安装的二进制文件（全局安装或位于 node_modules/.bin）时，该命令才是正确的。如果 agentmark --version 可以解析，但 init / dev / doctor 不是已知命令，则说明安装了错误的 agentmark——请重新安装 @agentmark-ai/cli。

如何查找最新信息

你的训练数据已经过时。在回答任何与 AgentMark API、CLI 标志、提示词语法或文档内容有关的具体问题之前，请按以下顺序查找。**这是整个技能唯一的文档查找优先顺序——所有工作流都遵循此顺序；不要另行编造顺序。**文档是唯一的信息来源；下面每一步都只是读取文档的方式。

1. CLI 接口 — 运行 agentmark <command> --help。这是命令标志、参数和行为的权威来源。绝不要凭记忆推断标志。
2. 先确定方向 — 获取 https://docs.agentmark.co/llms.txt，这是包含所有文档页面的机器可读索引，然后再选择正确的页面阅读内容。先确定方向，才能避免凭记忆编写内容（这正是产生 <Human> 或 metadata.model.name 这类无效提示词格式的原因）。
3. 以 Markdown 格式阅读页面 — 在 docs.agentmark.co 的 URL 后追加 .md，然后使用 WebFetch 获取。每个页面都提供 Markdown 格式，所需 token 远少于 HTML；这是阅读文档内容的主要方式。
4. 搜索备用方案 — 只有在 llms.txt 中找不到正确页面时，才查询文档 MCP 服务（https://docs.agentmark.co/mcp）；它会搜索同一套文档并返回匹配的页面。MCP 是文档的接口，而不是单独的信息来源。
5. 仅限离线时使用 — 如果网络受阻，随附的 reference/*.md 文件可在本地使用，并且是自动生成的（版本与此技能匹配）。请阅读这些文件，而不要凭记忆复述——但它们只是最后的备用方案；如果与在线文档不一致，应以在线文档为准。

绝不要凭记忆写出 API 接口、CLI 标志或提示词语法——凭记忆复述标志会导致虚构出 --dataset（它并不存在）。如果两个来源不一致，应以在线文档为准。

运行时模型

AgentMark 分为两个接口。务必区分清楚，否则你会去寻找并不存在的端点。

• 网关 / Cloud API（api.agentmark.co）— 用于可观测性和配置。存储提示词、轨迹、评分、数据集和部署。**它不会执行提示词。**不存在 POST /v1/prompts/{name}/run 端点。如果你找不到资源上的“执行”操作，这是正常的。CLI 的功能经过刻意筛选（dev、login、logout、link、run-prompt、run-experiment、build、pull-models、generate-types、generate-schema），并且有意保持精简。如需以编程方式使用完整的 Cloud API 接口——配置应用、列出实验、管理部署、查询轨迹——请在本地运行 agentmark-mcp MCP 服务，并让 IDE Agent 调用其工具。请参阅 workflows/headless-with-mcp.md。对于没有 MCP 客户端的定制自动化（例如 CI 中的 Python 脚本），网关支持纯 REST——使用 ~/.agentmark/auth.json 中的会话 bearer，或使用 AGENTMARK_API_KEY 调用它。
• SDK（@agentmark-ai/sdk；ApiLoader 随 @agentmark-ai/prompt-core/loader-api 一起提供）— 用于执行。客户代码使用 SDK 加载已部署的提示词模板，并直接调用 LLM 提供商。设置 AGENTMARK_API_KEY 和 AGENTMARK_APP_ID 后，轨迹会自动转发到网关。

因此，“在生产环境中运行提示词 v1”指的是使用 SDK 的客户应用，而不是调用网关。关于无头工作流（提交 → 推送 → 轮询 → 使用），请参阅 workflows/deploying.md。

项目结构

my-project/
├── agentmark.json              # Project config (required)
├── agentmark/                  # Prompts directory (path set by agentmarkPath in config)
│   ├── greeting.prompt.mdx
│   └── qa-bot/
│       ├── prompt.prompt.mdx
│       └── data.jsonl          # Dataset
├── .agentmark/                 # Auto-generated config (gitignored)
│   └── dev-config.json         # Local dev state, linked app metadata
├── agentmark.client.ts         # TS AgentMark client (loader + scorers)
├── dev-entry.ts                # Local dev webhook entry — `agentmark dev` boots this
├── handler.ts                  # Cloud deployment entry
└── .env                        # API keys, loaded automatically by the CLI

• agentmark.json — 最低配置：{"agentmarkPath": ".", "version": "2.0.0", "mdxVersion": "1.0"}。规范布局使用 "."，不要使用 "/"。
• 提示词是 .prompt.mdx 文件。YAML frontmatter 包含 name、一个生成类型配置块（text_config、object_config、image_config 或 speech_config），其中包含 model_name，以及一个可选的 test_settings 块，用于配置数据集和评测。正文采用 TemplateDX（Markdown 中类似 JSX 的标签）。不要将 model_name 或 evals 放在顶层——它们属于各自的配置块。
• 数据集是 .jsonl 文件。API 路径参数中使用的 datasetName 是不带 .jsonl 扩展名的文件路径，并经过 URL 编码。

设置或调试项目

每当你将 AgentMark 接入项目——无论是通过全新的 agentmark init 脚手架，还是接入现有仓库——或者遇到异常（agentmark dev 无法启动、提示词无法运行、没有显示跟踪记录）时，都先运行 agentmark doctor。 它会静态检查整个脚手架，并一次性列出每个问题的具体修复方法，因此它既是你的设置清单，也是调试工具。与其猜测新项目或尚未完成接线的项目还缺什么，不如让 doctor 列出所有问题：每个缺漏都会附带一条 fix，告诉你（或用户）接下来要采取的确切步骤。它会检查：

• 配置：agentmark.json 是否存在且有效、agentmarkPath 是否能解析（不能是 "/"）、是否包含必需的键，以及是否存在未知键的拼写错误
• 设置文件：客户端（agentmark.client.ts / agentmark_client.py）、开发服务器入口，以及受管部署处理程序（handler.ts / handler.py）
• 提示词能否解析并声明 model_name；提示词模型是否包含在 builtInModels 中（非空列表是允许列表，因此 prompt-core 会拒绝其中未列出的模型）
• 依赖：运行时软件包是否确实已安装（可从项目中解析），而不只是列在 package.json 中——@agentmark-ai/prompt-core（关键依赖：客户端和 dev 入口都会导入它，因此已声明但未安装的 prompt-core 会导致检查失败；这是 dev / --smoke 启动时以状态码 1 退出的首要原因）和 @agentmark-ai/sdk（用于跟踪和云端执行运行器；此项为警告）。无需特定于 SDK 的适配器——你可以自行提供 SDK，并通过 @agentmark-ai/prompt-core 将其接入——使用中立的渲染方式（createAgentMark）或小型执行器（createExecutor）

然后，agentmark doctor --smoke 会端到端运行一个提示词，并验证发出的跟踪记录能以正确结构完成往返（包含模型、令牌用量、输入和输出）。添加 --boot 后，它会为你启动并停止 agentmark dev，因此只需运行一条命令。这能捕获以下静默故障：模型实际上从未运行（密钥错误或 SDK 不匹配），或由于跟踪未接入而导致模型跨度消失；你无需猜测是哪一种情况。它不了解任何特定提供商或密钥，而是通过实际运行间接测试，因此无需维护针对各个提供商的检查清单。静态检查只读，随时可以安全地重复运行；--smoke 会实际调用模型（消耗令牌并发出跟踪记录），因此应在验证更改时使用，不要短时间内反复运行。

以编程方式使用。 运行 agentmark doctor --json 并解析 { ok, counts, results: [{ id, group, title, status, detail, fix }] }。status 的值为 pass | warn | fail | skip 之一；每个 id 都是稳定的（例如 config.schema、deploy.handler、deps.sdk、smoke.run、smoke.evals、smoke.trace），因此可根据 id / status 执行分支并应用 fix。实时的 --json 输出是 id 集合的权威来源；不要凭记忆将其硬编码。--strict 会将警告视为失败；退出码为 0 表示没有失败项。当 fix 显示“ask your coding agent to 'Set up AgentMark'”时，这条指令是给你的：请运行 setup-and-integration，而不是将其转交出去。

“容易让 Agent 出错的约定”中的大多数陷阱都会显示为一项 doctor 检查失败。手动调试前，先运行它；如需确认确切的标志，请运行 agentmark doctor --help 或查看 reference/cli-commands.md。

常见工作流

任务	文件
设置 AgentMark（新建脚手架或现有项目）——先运行 doctor	agentmark doctor；然后参阅 workflows/setup-and-integration.md
调试损坏的设置或运行	agentmark doctor（加上 --smoke）；参阅上文设置或调试项目
编写新提示词	workflows/creating-prompts.md
为实验构建数据集	workflows/building-datasets.md
对数据集运行提示词	workflows/running-experiments.md
添加评估以把关质量	workflows/using-evals.md
部署到 AgentMark Cloud	workflows/deploying.md
查看提示词运行的跟踪记录	workflows/observability.md

容易让 Agent 混淆的约定

• run-prompt ≠ run-experiment。 run-prompt <file> 会使用你传入的 --props 执行单条提示词。run-experiment <file> 会针对其关联数据集中的每一行执行提示词，并运行评估。两者不可混用。
• agentmark dev 会运行完全本地的服务。 项目关联后（通过 agentmark link），跟踪会自动转发到 AgentMark Cloud；使用 --no-forward 可禁用转发。dev 没有 --remote 标志——该标志已在 0.13.0 中移除，同时移除的还有 @agentmark-ai/connect WebSocket 包。如果你在旧内容中看到 dev 使用 --remote，请忽略。
• 部署基于 Git。 将 Git 提供商（GitHub 或 GitLab）连接到你的 AgentMark Cloud 应用，然后推送到已配置的分支——AgentMark 会自动构建和部署。没有 deploy CLI 命令；推送到受监视分支就是部署触发操作。请参阅 workflows/deploying.md。当有人紧急要求“修正后的部署命令”时，其实没有什么标志需要修正——调用 agentmark deploy 的脚本会失败，因为该命令并不存在；你能提供给他们的最快解决方案就是执行 git push，推送到受监视分支。只说“该命令不存在”却不告诉他们应改为推送，会让他们不知所措；“不要解释”绝不意味着“隐瞒可用的替代方案”。
• CLI 面向人类；MCP 服务面向 Agent。 agentmark CLI 有意保持精简：dev、login、logout、link、run-prompt、run-experiment、build、pull-models、generate-types、generate-schema。当 Agent 需要以编程方式调用 Cloud API（创建应用、生成 API 密钥、连接 Git 提供商、列出部署、查询跟踪，……）时，它会运行 agentmark-mcp MCP 服务并使用其中的工具。工具由 api.agentmark.co/v1/openapi.json 自动生成，因此 Agent 可用的接口始终与网关保持同步。请参阅 workflows/headless-with-mcp.md。
• 数据集名称的编码方式因端点而异。 对于 GET /v1/datasets 的 ?name=X 查询过滤器，传入不带 .jsonl 扩展名的叶名称（精确匹配）。对于 /v1/datasets/{datasetName}/rows* 下的 POST 端点，传入经 URL 编码的完整路径（例如 agentmark%2Fqa-bot%2Fdata），仍不带扩展名。
• 写入请求体中绝不要发送 tenant_id——它会根据你的凭证确定。 每次 Cloud API 写入（生成 API 密钥、追加数据集行、创建标注队列或警报）都会将新行归入 AGENTMARK_API_KEY / 会话 bearer 所属的租户。数据库会静默覆盖你传入的任何 tenant_id，将其替换为该租户——不会报错——因此你尝试归入另一个租户的行只会落在你自己的租户下。（注意：配置/管理应用——create_app / update_app / delete_app——属于租户级操作，需要 会话 bearer；应用级 AGENTMARK_API_KEY 无法执行这些操作。请参阅 workflows/headless-with-mcp.md § Authentication。）如果你在排查“为什么资源出现在与我指定不同的租户下”，原因就在这里：覆盖逻辑位于数据库触发器中，而非 API 处理程序中，因此阅读应用代码也找不到它。请完全省略此字段。
• 数据集行会将 props 包装在 input 中。 一行的格式为 {"input": {…props…}, "expected_output": …}。扁平行（props 位于顶层）会被 run-experiment 静默跳过——它会运行 0 行并因空集而“通过”，因此，扁平数据集上的绿色实验无法证明任何事情。请参阅 workflows/building-datasets.md。
• 模型 span 需要两项配置；span()/observe() 不算其中之一。 要查看生成 span（模型、令牌、输入/输出）：需要设置 sdk.initTracing({ registerGlobally: true })——AI SDK 会通过全局 tracer 发出该 span，而 AgentMark 的 tracer 默认相互隔离，因此不加此标志时，模型 span 会静默消失，但自定义 span 仍能正常工作——还需要在 prompt.format(…) 上启用遥测（例如通过 createPromptTelemetry）。请参阅 workflows/observability.md。
• 跟踪级输入/输出是在读取时推导出来的，绝不由执行器设置。 跟踪的输入/输出（跟踪列表、跟踪详情、doctor --smoke 的 traceShape 检查）会在读取时推导：根提示词运行 span 的 agentmark.input/agentmark.output（由 WebhookRunner 自动写入）优先；若没有，则回退到第一个/最后一个 GENERATION span。如果跟踪缺少 I/O，请修复埋点（模型 SDK 未发出 GENERATION span）或更新 runner——不要在执行器中添加 span 属性；执行器不负责这个边界。请参阅 workflows/observability.md § Where trace-level input/output come from。
• AgentMark 可通过一个中立接口与任意 SDK 配合使用——不存在针对特定 SDK 的适配器。 无论宿主调用什么（Vercel AI SDK、原始 OpenAI/Anthropic 客户端、Bedrock ConverseCommand、自定义客户端），集成都完全相同：将提示词渲染为 AgentMark 中立格式 { messages, text_config }，再交给该 SDK。绝不要寻找或搭建“适配器”。设置 AgentMark 时始终会搭建可运行的三件套——客户端 + dev-entry.ts + handler.ts——而不是只搭建进程内脚本。 agentmark dev 会从 dev-entry.ts 启动，以便在本地提供服务并运行提示词；搭建出的客户端会从该开发服务加载，因此跳过 dev-entry 会导致无法在本地运行，也无法使用 doctor --smoke --boot。“Path A”（loadTextPrompt + 在进程内调用你的 SDK，见 /build/running-prompts）与“Path B”（云端通过 webhook 运行提示词，执行器来自 connect-your-SDK）的区别在于宿主应用代码如何获取补全结果——它们是在三件套基础上的补充，并不是跳过 dev-entry 的理由。完整指南：/getting-started/client-setup。

参考资料

所有 reference/*.md 文件都会在每次发布时根据上游源自动生成。它们是此技能中最可靠的事实依据。手动编写的工作流文件可能会过时；这些文件不会，因为重新运行生成器是推送前检查的一部分。

• CLI 命令：reference/cli-commands.md — 根据 cli-src/index.ts 生成。建议使用 agentmark <cmd> --help 进行实时验证。
• Frontmatter 架构：reference/frontmatter-schema.md — 根据 prompt-core/src/schemas.ts（Zod）生成。以运行时信息为准。如果文档有出入，请以文档为准。
• Gateway API 接口（供 Agent 使用）：agentmark-mcp 会在启动时从 api.agentmark.co/v1/openapi.json 获取。资源名称是标签 slug；操作是 operationId。此处没有静态参考文件——规范太大且变更频繁。运行 agentmark-mcp 并调用 tools/list，或直接阅读规范，以列出可用工具。
• 模型注册表：没有静态参考文件——注册表变动太频繁（约每天同步一次），打包的快照无法保持最新，过时的列表还会错误地拒绝新发布的模型。提示词的有效 model_name 以项目自身配置的集合为准：运行 agentmark generate-schema 并读取生成的 model_name 枚举（运行时信息，项目级）。若要浏览或添加模型，请运行 agentmark pull-models；它会在运行时而非从已安装的 CLI 版本解析列表：@agentmark-ai/model-registry 会从 jsdelivr CDN 获取 models.json，该 CDN 镜像了公开仓库的 main 分支（agentmark-ai/agentmark@main/packages/model-registry/），因此添加到 main 的模型无需升级 CLI 即可显示——已安装的版本只决定离线时的底线。若网络故障或超时超过 5 秒，它会静默地回退到已安装 npm 包中打包的快照（不会报错——离线运行 pull-models 只会显示该版本中的较旧列表，因此没有列出某个模型绝不代表它不存在）。CDN 边缘缓存导致的延迟最长约 12 小时。不要凭记忆复述模型 ID——请对照 generate-schema / pull-models 验证。另请参阅 getting-started/client-setup。
• 完整文档：https://docs.agentmark.co
• 面向大模型的文档索引：https://docs.agentmark.co/llms.txt
• 完整文档语料：https://docs.agentmark.co/llms-full.txt
• 文档 MCP 服务：https://docs.agentmark.co/mcp

此技能不适用的情况

• 没有 AgentMark 项目背景的一般提示词工程问题——直接回答，不要强行套用 AgentMark 规范。
• 与提供商无关的大模型代码、原始 @anthropic-ai/sdk 或 OpenAI SDK 调用——不要引入 AgentMark 导入语句。
• 关于竞品平台（Langfuse、LangSmith、Phoenix、Braintrust、Traceloop）的问题——直接回答比较问题。如果用户随后决定使用 AgentMark，再回到此技能。

如果找不到支持 AgentMark 相关回答的文档，请明确说明，并链接至 https://docs.agentmark.co/llms.txt，方便用户查找相关页面。