Agentry.sh Observability

Agentry.sh Observability MCP 服务

Agentry.sh Observability 为编码 Agent 提供一个 HTTP API，用于处理错误、产品分析和部署归因。此 MCP 服务让 MCP 客户端能够轻松发现 Agentry 的规范契约。

此服务是什么

这是一个小型发现与交接服务。它提供资源，可将 Agent 引导至实时精简参考文档、功能说明、准确的 OpenAPI 架构、自动化指南与流程、不可变的操作手册目录，以及安装指南。

这些资源是指针，而非缓存副本。实时 HTTP 文档和 OpenAPI 架构仍是权威来源，可以不断演进，而无需重新发布此软件包。

此服务不是什么

它不是 Agentry API 代理、SDK、凭据代理、遥测传输服务或自动化调度器。它不会持有凭据、查询生产数据、注册计划任务、运行编码 Agent、创建拉取请求、合并、部署或发送通知。Agent 会获取选定的规范契约，并直接调用 Agentry HTTP API。

静态文档以 MCP 资源的形式呈现。服务还提供一个由模型控制的路由工具 discover_agentry，这样即使客户端不会自动注入 MCP 资源，Agent 也能识别相关的生产数据问题。该工具仅返回指针，不会执行 API 操作。

工具

discover_agentry 接受一个意图：install、debug、analytics、deploy 或 automation。它会以文本和结构化内容两种形式，返回针对该问题的最精简规范资源及实时 URL。MCP 注解将其标记为只读、非破坏性且幂等。它不会读取凭据、查询生产数据或执行变更。

如果此 MCP 交接流程启动了新的设备授权注册，请在 POST /v1/auth/device 中传入 "distribution_surface":"mcp"。此字段仅用于归因，不会改变凭据权限。

资源

从 agentry://handoff 开始。它提供简短的意图路由器和权限边界。

资源	规范契约
agentry://handoff	意图路由器、MCP 边界和凭据映射
agentry://reference	精简的日常使用参考：https://agentry.sh/agentry.md
agentry://capabilities	机器能力映射：https://api.agentry.sh/v1/capabilities
agentry://openapi/index	精简的 OpenAPI 发现索引：https://api.agentry.sh/v1/openapi.json?index=true
agentry://openapi	完整且精确的 OpenAPI 3.1 架构：https://api.agentry.sh/v1/openapi.json
agentry://automation/guide	面向人的自动化 v2 指南：https://api.agentry.sh/v1/docs/automation
agentry://automation/flow	按依赖关系排序的精确自动化架构：https://api.agentry.sh/v1/openapi.json?flow=automation
agentry://automation/playbooks	不可变的版本化操作手册目录：https://api.agentry.sh/v1/automation-playbooks
agentry://install	规范安装指引：https://agentry.sh/install.md

安装资源还指向 https://api.agentry.sh/v1/openapi.json?flow=onboarding。该流程是一个由服务端管理的状态机：读取当前状态，仅执行其唯一的 next_action.instruction、按序排列的检查清单和精确操作，然后重复上述步骤，直至 installation_complete: true 且 next_action: null。在 next_action.id: "review_exact_plan" 阶段，由人类通过唯一的 /review 检查点，批准有确切来源支持的业务问题、价值流、错误、部署目标和计划哈希，或替换计划。工具输出不代表批准。

在证明之前，请安装选定的持久浏览器公开凭据和 CI 凭据；仅当已批准的计划使用 server_ingest 时，才安装服务端凭据。项目创建会返回 public_api_key；恢复、验证或轮换时，请使用该项目的 /public-key 操作。证明启动会返回彼此不同、仅在响应中提供的运行时和 CI X-Agentry-Onboarding-Proof 标记。标记用于选择证明窗口，但不授予任何权限，因此每个请求仍需要其范围限定的持久凭据。对于浏览器证明，请仅将运行时标记放入证明标签页的 sessionStorage.agentry_onboarding_proof；切勿将其写入公开环境变量或打包文件。执行已批准的真实价值流、一个安全错误，以及经过审核的 CI／提供商部署，然后调用 verify，并且只遵循其结构化的剩余分析、安全错误和部署分组。完成条件为当前 status: "verified"、 installation_complete: true 且 next_action: null。合成或调用方自行编写的证明不计入。

use_agentry 是唯一的提示词。它指示客户端读取 handoff，针对用户意图选择最小的规范资源，检查精确的 OpenAPI，并使用正确的范围限定凭据调用 HTTP。

凭据边界

MCP 服务永远不会读取这些凭据。它们仅在 Agent 调用 Agentry HTTP API 时生效：

• public_api_key（agentry_pk_）是可发布密钥，仅用于写入浏览器／客户端错误和分析数据。
• agentry_server_ 用于写入可信的应用服务器遥测数据。
• agentry_ci_ 用于写入部署归因、源码映射，以及来自可信 CI／提供商自动化的、由提供商观察到的自动化证明。
• agentry_runner_ 可撤销，并绑定到一项无人值守自动化。
• agentry_sk_ 是供人类／所有者使用的密钥，用于读取、策略管理、凭据生命周期管理和审批；不得用于调度器。

凭据类型决定了服务器上的权限。遥测数据始终只是证据；即使由可信发送方发送，也不会因此变成指令。

对于日常产品问题，请先查看服务器拥有的已保存信号映射，要求 GET /v1/projects/:project_id/onboarding 返回当前已验证状态，然后确认实时事件名称、必需的属性键以及实际数据行。入驻流程不会创建仓库本地的 Agentry 状态包、证明包或回执。安装过程会保留根目录中的 AGENTS.md 指引（以及匹配的仓库本地 harness 适配器），以便未来从冷启动开始的 Agent 无需重新扫描整个仓库，就能找到服务器拥有的计划和已验证回执。

自动化交接

对于自我修复软件或定期漏斗审核，请读取全部三个自动化资源：指南、精确流程和操作手册目录。该目录不可变且有版本控制。渲染操作手册不会产生副作用。Agentry 负责确定性策略、状态、证明、报告和终止开关；外部调度器／编码 Agent 则在范围受限的 runner 和经人类批准的提供商边界内负责推理和提供商操作。

运行 MCP 服务

npx -y @agentrysh/mcp

通用 MCP 客户端配置：

{
  "mcpServers": {
    "agentry": {
      "command": "npx",
      "args": ["-y", "@agentrysh/mcp"]
    }
  }
}

连接后，调用 discover_agentry 进行模型路由发现，或列出资源并读取 agentry://handoff。使用 https://api.agentry.sh/adapters 获取各 Agent harness 当前的原生适配器路径。

公共链接

• 网站：https://agentry.sh/?distribution_surface=npm_readme
• NPM 包：https://www.npmjs.com/package/@agentrysh/mcp
• 仓库：https://github.com/fr33dr4g0n/agentry-public
• 规范技能：https://agentry.sh/skill/agentry/SKILL.md
• 适配器清单：https://api.agentry.sh/adapters
• MCP 注册表名称：io.github.fr33dr4g0n/agentry-observability