用视觉工具检查图片

当任务需要解读截图、架构图或照片中的信息时，Agent 可以使用 ViewImage 工具调用视觉模型进行观察与分析。

开始之前

• 图片已存在于运行时主机上，且 Agent 具有读取权限。手机或笔记本本地的路径不会自动在远程运行时中可用。
• Agent 具有调用 ViewImage 的权限。
• 已配置视觉模型路由，或者能自动探测到具备图片输入能力且已认证的模型。具体请参阅配置模型。
• 你已获得将该图片发送给所选模型服务商的授权。截图中如果包含凭据或私密信息，请在调用前先做脱敏处理。

操作步骤

1. 告诉 Agent 你要检查哪张图片以及需要提取什么信息：

   查看 ./screenshots/login-error.png，帮我看看错误弹窗里显示的完整文字是什么。
   

2. Agent 会调用 ViewImage。如果配置正确，工具会返回视觉观察结果以及媒体类型、字节大小、分辨率等元数据。

3. 对照你的问题阅读观察结论。对于相同的图片内容和提示词，运行时可以复用缓存的观察记录；重复提问不一定会再次发起服务商调用。

确认结果

核对返回的文件元数据是否对应你预期检查的图片文件。确认结果中包含具体的视觉观察文本：仅仅返回文件元数据并不代表模型已对图片进行了解读。对于模棱两可的内容（特别是较小的字迹），应视为待验证的观察推测，必要时核对原图。

故障排查

• 文件缺失或不可读： 检查运行时主机上的文件路径以及 Agent 当前的活动 Workspace。如果相对路径定位出现偏差，请使用已确认的绝对路径。
• vision_adapter_unavailable： 阅读返回的选择诊断信息。按照配置模型检查 vision.default 设置、凭据有效性、图片输入能力以及协议传输支持情况。
• 服务商调用错误： 重试前先检查返回的鉴权、网络或格式错误说明。
• 观察结论遗漏关键细节： 尝试收窄提问范围，或提供局部裁剪放大图。切勿推测图片中并未清晰展示的文字。

规格限制

支持的文件格式、模型选择机制以及完整的响应结构，请参阅图片观察参考。