Stirrup多模态能力详解：让Agent看懂图片、视频与音频的完整原理

【免费下载链接】StirrupThe lightweight framework for building agents项目地址https://gitcode.com/gh_mirrors/st/Stirrup点击查看免费下载Stirrup 是一个轻量级的 Python Agent 框架除了执行代码和联网搜索它内置了完整的多模态支持Agent 可以接收和输出图片、视频、音频框架会自动完成格式校验、缩放、转码并翻译成各家大模型 API 能理解的结构。本文带你从零看懂 Stirrup 多模态能力的完整原理并学会最常用的让 Agent 看图配置。一张图看懂多模态能力在框架中的位置Stirrup 的多模态能力由四层组成自底向上分别是层级核心组件源码位置内容块ImageContentBlock/VideoContentBlock/AudioContentBlockmodels.py工具层view_image工具、浏览器截图、MCP 媒体转换view_image.py、mcp.py客户端层媒体块 → OpenAI 格式自动转换utils.py框架层消息混合、图片提取、缓存持久化agent.py、cache.py三大媒体内容块统一的多模态数据结构所有媒体在 Stirrup 中都是内容块ContentBlock一条消息的content可以同时混合文字 图片 视频 音频定义见 Content 类型。图片自动缩放 完整性校验ImageContentBlock支持 PNG、JPEG、WebP、GIF、BMP、TIFF、PSD 等格式。它做两件关键的事入库前校验用filetype嗅探真实 MIME 类型并对照白名单再用 PIL 的verify()做轻量损坏检查models.py——损坏的文件会在构造时就报错而不是等到请求 API 才失败发送前自动缩放to_base64_url()会把超过100 万像素RESOLUTION_1MP见 constants.py的图片按原比例缩到 1MP 以内统一转成 RGB 的 PNG data URL控制 token 成本。视频自动转码为 480P MP4VideoContentBlock接受 MP4、MOV、AVI、MKV、WMV、FLV、WebM、MPEG、动图 GIF 等格式models.py。发送时会通过 moviepy把分辨率降到480P640×480RESOLUTION_480P统一转码为H.264 AAC 的 MP4presetveryfast保证转码速度以data:video/mp4;base64,data URL 形式进入请求。也就是说你丢一个 MKV 进去模型收到的是一个规整的 480P MP4中间过程完全不用你操心。音频自动转码为 MP3AudioContentBlock支持 MP3、WAV、AAC、FLAC、OGG、PCM 等常见音频models.py。to_base64_url()默认以192k 比特率用 libmp3lame 转成 MP3再交给模型。一个统一的守门员三种媒体块都继承自BinaryContentBlock基类models.py二进制数据以 base64 形式安全存储并共享同一套MIME 白名单校验 损坏探测机制。格式不支持时抛出清晰的Unsupported mime_type错误行为可预期。自动格式转换媒体块如何变成模型 API 请求不同大模型厂商的 API 对媒体字段的写法并不相同。Stirrup 的客户端在每次请求前调用content_to_openai()统一完成翻译utils.py内容块Chat Completions 格式Open Responses 格式图片image_urlbase64 data URLinput_image音频input_audiobase64 formatinput_audio视频fileMP4 data URLinput_file对应源码Chat Completions 走 content_to_openaiResponses API 走 open_responses_client.py。你只需面向 Stirrup 的内容块编程换客户端时多模态行为保持一致。让 Agent 自主看图view_image 工具多模态输入之外Stirrup 更强大的设计是Agent 可以在任务过程中自己看自己生成的图。典型场景是用 matplotlib 画张图然后检查图表有没有问题。工作原理4 步Agent 通过code_exec工具在沙箱里执行代码生成chart.pngAgent 调用view_image工具并传入路径工具从执行环境读出文件字节包装为ImageContentBlock连同说明文字一起返回给模型base.py模型看到图表判断坐标轴、标签是否正常决定修正代码还是结束任务。零配置的环境自动检测ViewImageToolProvider设计得非常省心view_image.py可以显式传入执行环境实例ViewImageToolProvider(exec_env)也可以什么都不传它会在会话启动时自动从 Agent 会话状态里找到同一个CodeExecToolProvider两种工具在tools列表中的顺序无关。这意味着它天然兼容全部三种代码执行后端——本地临时目录、Docker 容器、E2B 云沙箱code_backends/沙箱里生成的图片一样能被模型直接看到。纯文本模型的降级策略如果你的模型不支持图像Agent 有个贴心的开关text_only_tool_responses默认True它会把工具返回中的图片块提取为独立的用户消息并在工具结果里写明图片将随下一条消息提供agent.py最大限度兼容各家 API 对工具消息类型的限制。其他三个多模态入口直接传图给 Agentsession.run()接受消息列表往UserMessage的 content 里放ImageContentBlock(data图片字节)即可例如 user_input_example.py 这类场景的扩展。测试用例 test_view_image.py 展示了内容块的构造方式MCP 服务器MCP 工具返回的图片/音频内容会被_convert_mcp_content()自动转换为 Stirrup 的内容块mcp.py外部 MCP 生态里的多模态结果可以无缝进入对话浏览器截图Browser Use 工具集内置screenshot工具网页截图直接以ImageContentBlock返回browser_use.py让 Agent 实现操作网页 → 截图 → 视觉核验的闭环。缓存与恢复也能带上媒体多模态消息进入会话缓存时媒体块会被 base64 序列化并记录kind判别字段cache.py任务中断后恢复会话图片、视频、音频上下文原样保留。此外当 API 因图片数量或请求体积拒绝请求时框架还能触发自动压缩重试concepts.md。快速上手3 步让 Agent 看懂图片from stirrup import Agent, ImageContentBlock from stirrup.tools import LocalCodeExecToolProvider, ViewImageToolProvider agent Agent( clientclient, nameimage_agent, tools[ LocalCodeExecToolProvider(), ViewImageToolProvider(), # 自动检测执行环境 ], ) # 第 1 步会话中让 Agent 生成图片 # 第 2 步Agent 自动调用 view_image 查看 # 第 3 步也可以直接喂图 await session.run([ UserMessage 携带 ImageContentBlock(dataopen(cat.png,rb).read()), ])完整的联网找图 视觉描述示例见 view_image_example.py官方文档页见 docs/api/tools/view-image.md。总结Stirrup 多模态设计的 4 个亮点亮点说明️ 开箱即用图片/视频/音频三大内容块格式校验与转码全自动 格式自适应图片缩到 1MP、视频转 480P MP4、音频转 192k MP3控制 token 成本 客户端无关统一的content_to_openai转换层换模型不换代码 Agent 闭环view_image让生成 → 查看 → 修正形成自主迭代对新手来说记住一句话就够了在 Stirrup 里多模态就是普通的内容块——你只管把图片字节放进消息或让 Agent 调用view_image缩放、转码、API 格式差异、缓存持久化这些脏活框架全部替你做好了。赞分享【免费下载链接】StirrupThe lightweight framework for building agents项目地址https://gitcode.com/gh_mirrors/st/Stirrup点击查看免费下载相关推荐多模态能力实测Muse-Spark-Open-816B-A42B-3bit如何看懂图片与视频多模态能力实测Muse Spark Open 816B A42B 3bit如何看懂图片与视频 Muse Spark Open 816B A42B 3bit 是人工智能大模型多模态本地部署模型量化如何让Qwen3.5-4B-w8a8看懂图片和视频多模态大模型推理实战完整教程如何让Qwen3.5 4B w8a8看懂图片和视频多模态大模型推理实战完整教程 Qwen3.5 4B w8a8 是 Qwen3.5 4B 的 W8A8 量化版大模型模型量化本地部署AscendCustomTkinter5 个要点快速打造现代 Python GUI 界面CustomTkinter5 个要点快速打造现代 Python GUI 界面 CustomTkinter 是基于 Tkinter 的现代化 Python UIUI组件桌面应用上一篇如何用 kpl_list 拉取 A 股每日涨停榜单Vibe-Trading 打板数据四步上手下一篇如何和家人共享一套 NodeWarden 密码服务器邀请码注册与多用户管理完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考