跳至文档正文
文档目录 · Agent Guide

Developers

Agent Guide

Agent 接入顺序与行为边界:发现能力、查询规范实体、保留未知、追溯证据,并正确处理身份歧义与接口错误。

Agent 的六步顺序

Discover capabilities → Query canonical entities → Preserve unknown values → Follow evidence → Never infer identity from names alone → Treat API errors as contract signals.

发现能力 → 查询规范实体 → 保留未知 → 追溯证据 → 不凭名称推断身份 → 把接口错误作为契约信号处理。

发现能力

先读 Agent Card;MCP 先 initialize,再 tools/list,使用返回的 inputSchema 构造请求。部件任务额外检查 capability,语义不清楚时读取 知识协议plannedSkills 不是已开放工具。

机器入口无法读取时,报告发现失败,不根据页面标题或旧缓存臆造工具。robots.txt 用于爬虫抓取约定,不能代替接口鉴权与权限判断。

查询实体,再形成判断

步骤做法遇到缺口时
搜索REST search 或 MCP search_robots.query返回空集合只表示本次查询未找到
消歧读取详情中的 identity.canonicalIdmatchTypeambiguouscandidates名称命中有歧义时保留候选,不能替用户合并
引用机器人保留规范 ID;公司使用解析后的 canonicalName 与 aliases厂商未知时保留空值,不由产品名猜厂商
核证跟随 provenance 或逐条 evidence,核对型号、字段、时间和测试条件只有证据 ID / 数量时,说明证据全文尚不可读
表达结论区分事实、某主体的声明、观点及审核状态来源冲突时列出双方主张与时间,保留冲突

例如搜索 G1 后,应通过厂商与返回的规范 ID 确认候选,再查询详情和状态。名称相同并不意味着对象相同;别名相同也不授权创建或合并实体。

Unknown 是需要保留的信息

null、缺失字段、缺少规格行、空集合、显式 stateStatus: unknownstateStatus: conflict 含义不同。不要统一转成 0false 或“没有此能力”。空的 states 表示没有查到相应状态记录,不等于服务端生成了一条 unknown 断言。

confidence 是系统记录的置信度,不是来源真实性的证明。recordUpdatedAt 是记录更新时间,不是发布日期或现场验收时间。部件匹配的 partial / missing 不能当作不满足,也不能升级为满足;详见 模型Evidence

错误也是契约

  • REST 400 + INVALID_QUERY_PARAMETER:按 allowedParameters 修正参数名,不删除约束后把宽泛结果当成原查询答案。
  • MCP error.code = -32602:修正未知参数、必填项或顶层类型,重新检查 inputSchema
  • MCP result.isError = true:工具执行失败,即使 HTTP 为 200 也不能当作成功;compare_robots 还需逐项检查 robots[*].error
  • 404:回到搜索与身份确认;401/403:停止并检查授权;429/5xx:有限重试或报告不可用,不制造空的成功结果。

REST 校验范围与响应形状并非全站统一,详见 错误契约

可以做什么,不能做什么

可以读取公开数据、保留来源的比较结果,并按 贡献协议 提交 URL、观察材料、证据或冲突报告。提交须符合用户任务授权;回执应继续按协议读取状态。

贡献进入待审流程,canonicalWrites: false。不能把提交成功解释为事实已被采纳,不能绕过审核修改 canonical 数据,也不能把收录、宣称兼容或参数匹配当成交付保证。商家账户与运维接口有各自权限,不属于公共 MCP 工具范围。

实现依据:emibot/src/lib/mcp-tools.tsemibot-rs/src/query_validation.rsemibot-rs/src/routes/robots.rsemibot-rs/src/routes/world_state.rs