Agentry - 代理原生分析与日志记录
Agentry 是为编码代理提供的原生分析和日志记录工具。它通过一个 HTTP API 涵盖产品分析、错误日志记录和部署归因，使代理能够回答用户做了什么、出了什么问题以及什么发生了变化。
使用此技能进行 Agentry 的安装/设置、产品分析、日志记录、错误监控、部署跟踪、生产调试以及日常的 Agentry 数据读取。不要将此文件视为 API 参考；它是一个访问实时文档的紧凑入口。
接下来获取什么
- 安装或设置 Agentry：获取 https://agentry.sh/install.md。
- 设置后回答产品、可靠性、案例、分析或部署相关问题：获取 https://agentry.sh/agentry.md。
- 探索 API 界面以及 3 写 / 3 读模型：从 https://api.agentry.sh/ 开始。
- 检查精确的请求/响应格式：获取 https://api.agentry.sh/v1/openapi.json；使用
?flow=、?tag=、?path=&method=或?index=true进行过滤。 - 安装或刷新未来会话的适配器：获取 https://api.agentry.sh/adapters 并写入每个与检测到的代理框架匹配的适配器。
对于非浏览器的直接 HTTP 调用，请使用自定义 User-Agent 头；默认客户端（如 Python-urllib）可能被阻止。浏览器 fetch 使用浏览器自身的 User-Agent，无法手动设置此头。
安装工作流
安装 Agentry 时，获取 https://agentry.sh/install.md 并遵循该流程。从仓库的重要业务问题以及漏斗/业务逻辑流程开始。让 POST /v1/install/plan 从实际代码库中推导出事件、属性、错误面和部署证明。不要手动编写通用事件目录。
在宣布成功之前，保存信号映射和实现报告，然后验证批准的遥测数据正在流动。
思维模型
Agentry 有三条写入路径和三个读取概念。
使用 AGENTRY_DSN 写入应用运行时数据：
POST /v1/logs/用于错误、异常和操作故障。POST /v1/analytics/用于产品、用户、漏斗和业务事件。
仅在 CI/提供商后部署自动化中，在成功发布后，使用相同的 AGENTRY_DSN 写入部署归因：
POST /v1/deploys/用于发布归因。
使用 AGENTRY_API_KEY 进行读取：
- 案例： 出了什么问题。从
GET /v1/projects/:project_id/cases开始，然后是GET /v1/cases/:case_id。 - 分析： 用户做了什么。从保存的信号映射、最新验证报告、答案合约、事件名称和属性键开始；然后使用查询蓝图进行常见读取，或使用
POST /v1/projects/:project_id/analytics/query进行自定义 HogQL。 类似表格的 Agentry 查询读取返回对象形状的rows；不要从面向代理的端点读取 PostHog 风格的results。 - 部署： 什么发生了变化。使用
GET /v1/projects/:project_id/deploys。
查询蓝图、事件名称、公共查询、健康检查和后续步骤都是围绕这三个读取概念的辅助工具。公共查询 URL 和仪表盘是可选的输出面，而不是证明底层产品问题可回答的证据。
对于日常问题，在选择查询蓝图或自定义 HogQL 之前，请阅读保存的信号映射、最新验证报告、答案合约、事件名称和属性键。如果所需的事件/属性缺失，请说明缺失了什么，并连接或触发该产品流程，而不是发明一个指标。
认证
从环境变量或 ~/.agentry/credentials.json 中读取 AGENTRY_API_KEY；从 AGENTRY_PROJECT_ID 或已提交的 .agentry/config.json 中读取 project_id。如果没有 API 密钥，使用 POST /v1/auth/device 启动设备流程。运行时数据摄取使用 AGENTRY_DSN。
事实来源
不要依赖此已安装的文件获取端点详细信息。请获取上述实时文档；它们具有权威性，并且可以独立于适配器进行更新。