使用 Swarms Agent 构建多模态视觉智能体：Nano Banana Jarvis Agent 实战指南

使用 Swarms Agent 构建多模态视觉智能体：Nano Banana Jarvis Agent 实战指南

【免费下载链接】swarmsThe Enterprise-Grade Multi-Agent Orchestration Framework. Website: https://swarms.ai项目地址: https://gitcode.com/GitHub_Trending/swar/swarms

导读

本文基于仓库中 nano_banana_jarvis_agent 示例目录，讲解如何在 Swarms 框架下用Agent封装视觉语言模型（VLM），实现图像理解、图像标注与图像生成三类多模态能力。读完本文，你将掌握Agent.run()传入图像的核心用法、关键初始化参数（动态温度、动态上下文窗口、循环控制）的底层行为，并能够举一反三构建自己的"看图说话""AR 标注""文生图"智能体。

示例目录总览

examples/guides/nano_banana_jarvis_agent/目录结构如下：

整个示例聚焦于一个核心命题：用同一套Agent抽象，同时驾驭"看图"与"生图"两种能力。README 中明确说明该示例用于演示 vision 与 multimodal 能力，包括图像分析（image analysis）、图像生成（image generation）与视觉理解（visual understanding），下文将逐一展开。

一、主实现：Jarvis 图像标注 Agent

jarvis_agent.py 是目录的核心示例，完整代码如下：

from swarms import Agent SYSTEM_PROMPT = ( "You are a location-based AR experience generator. Highlight points of interest in this image and annotate relevant information about it. " "Return the image only." ) # Agent for AR annotation agent = Agent( agent_name="Tactical-Strategist-Agent", agent_description="Agent specialized in tactical strategy, scenario analysis, and actionable recommendations for complex situations.", model_name="gemini/gemini-2.5-flash-image-preview", dynamic_temperature_enabled=True, max_loops=1, dynamic_context_window=True, ) out = agent.run( task=f"{SYSTEM_PROMPT} \n\n Annotate all the tallest buildings in the image", img="hk.jpg", )

1.1 系统提示词设计：把角色写进任务

这里没有使用system_prompt参数，而是将角色定义直接拼进task：

You are a location-based AR experience generator. Highlight points of interest in this image and annotate relevant information about it. Return the image only.

这种写法的用意是让模型始终以"AR 体验生成器"的身份对图像作答，并约束输出形态（Return the image only.）。配合运行时的具体指令Annotate all the tallest buildings in the image，就构成了一个完整的"给城市天际线照片做地标标注"任务。示例图片 hk.jpg（788×380 横向照片）正是为这类"图片中最高建筑标注"场景准备的输入。

1.2 模型选择：图像输入 + 图像输出的 Gemini 模型

示例选用gemini/gemini-2.5-flash-image-preview作为model_name。这个模型同时具备读取图片与输出图片的能力，因此能承担本文两类任务。需要说明的是：模型名以gemini/前缀标识，经由 LiteLLM 统一接入（仓库中Agent底层即通过LiteLLM与LLMManager驱动模型，见 swarms/structs/agent.py 的 imports）。若你本地可用的图像模型不同，可以直接替换model_name字符串，示例代码中也注释了"Replace with your preferred image generation model if available"。

1.3 关键初始化参数逐个拆解

对照 swarms/structs/agent.py 的Agent.__init__签名（第 311 行起），示例中四个参数的含义如下：

• agent_name/agent_description：Agent 的身份标识与职责描述。初始化时self.id = generate_id("agent")生成唯一 ID，agent_name默认"swarm-worker-01"。在仓库内部，agent_description还会参与系统提示词的自动拼装（见build_agent_system_prompt与agent_roles机制）。
• dynamic_temperature_enabled=True：开启动态温度。源码中Agent.run的主循环里，每个循环都会检查该开关并调用self.dynamic_temperature()（swarms/structs/agent.py），其实现为self.llm_manager.randomize_temperature()——即在 0.0～1.0 之间随机重置 LLM 温度，用于增加多轮输出的探索性，避免生成结果过于保守或雷同。
• max_loops=1：限制推理循环次数为 1，即单次"任务→模型→输出"，适合标注、生成这类一次性任务。若设为"auto"，Agent.run会转入自主循环模式（_run_autonomous_loop，计划→子任务→总结），详见源码第 3346 行。
• dynamic_context_window=True：启用动态上下文窗口。初始化后该值被存入self.dynamic_context_window，并在构建 LLM 参数时传递给底层封装（源码第 1010 行dynamic_context_window=self.dynamic_context_window），用于按需估算与调整上下文长度，降低超长多模态输入带来的截断风险。

1.4Agent.run()的图像输入机制

示例通过agent.run(task=..., img="hk.jpg")传入单张图片。从源码看，run()的完整签名是（swarms/structs/agent.py）：

def run( self, task: Optional[Union[str, Any]] = None, img: Optional[str] = None, imgs: Optional[List[str]] = None, correct_answer: Optional[str] = None, streaming_callback: Optional[Callable[[str], None]] = None, n: int = 1, *args, **kwargs, ) -> Any

img参数的 docstring 明确指出支持四种输入形态：

• 本地文件路径：如示例中的"hk.jpg"；
• URL：如"https://example.com/image.png"；
• Data URI：如"data:image/jpeg;base64,..."；
• 原始 Base64 字符串：可直接把图片读成 base64 传入。

若需要一次分析多张图，使用imgs=["a.png", "b.png"]传入列表；run()内部在_run()中会把图像输入交给底层 LLM 调用（源码第 1459 行将img=img传入 llm_kwargs）。在进入主循环前，_run()还会调用check_model_supports_utilities(img=img)（源码第 1352 行）校验当前模型是否支持视觉能力。

二、图像生成：Nano Banana 文生图 Agent

img_gen_nano_banana.py 展示如何用同一个Agent类完成"文字→图像"：

from swarms import Agent IMAGE_GEN_SYSTEM_PROMPT = ( "You are an advanced image generation agent. Given a textual description, generate a high-quality, photorealistic image that matches the prompt. " "Return only the generated image." ) image_gen_agent = Agent( agent_name="Image-Generation-Agent", agent_description="Agent specialized in generating high-quality, photorealistic images from textual prompts.", model_name="gemini/gemini-2.5-flash-image-preview", # Replace with your preferred image generation model if available dynamic_temperature_enabled=True, max_loops=1, dynamic_context_window=True, ) image_gen_out = image_gen_agent.run( task=f"{IMAGE_GEN_SYSTEM_PROMPT} \n\n Generate a photorealistic image of a futuristic city skyline at sunset.", ) print("Image Generation Output:") print(image_gen_out)

2.1 与标注 Agent 的异同

两者结构完全同构，区别只在提示词与任务：

这说明 Swarms 的Agent是模型无关的统一抽象：只要底层模型（经由model_name+ LiteLLM）支持对应能力，同一个 Agent 既能当"眼睛"也能当"画笔"，无需更换类或框架。

2.2 为什么提示词里要强调输出形态

示例在两个提示词中分别追加了Return the image only.与Return only the generated image.。对图像输出型模型而言，这一句是关键的输出模态约束——它可以抑制模型"既出图又附一大段文字解释"的倾向，让 Agent 的输出保持干净、可直接消费。这也是多模态 Agent 工程中"把格式约束写进提示词"这一最佳实践的直观体现。

三、配套素材与标注结果

目录提供了四张不同题材的输入图片，方便你快速替换测试：

• hk.jpg：香港城市天际线（788×380），对应示例中"标注最高建筑"的任务；
• miami.jpg：迈阿密城市景观（2000×920 宽幅）；
• building.jpg：单体建筑（257×589 竖构图）；
• image.jpg：通用示例图。

此外，annotated_images/ 目录存放了运行标注 Agent 后产出的带标注结果图（多张 1472×704 横向截屏与竖版图）。它们与本文"图像标注"主题直接相关，可作为你运行示例后对比输出形态的参照物。

四、运行前置条件与实操步骤

4.1 环境准备

1. 安装 Swarms：从仓库根目录安装依赖，例如pip install -r requirements.txt（也可参考 pyproject.toml 的工程配置与 scripts/setup.sh）；
2. 配置模型密钥：Agent底层经由 LiteLLM 调用gemini/*模型，因此需要配置对应提供商的 API Key 环境变量（Gemini 系列通常对应GEMINI_API_KEY）；若替换为其他图像模型，请按该提供商要求配置密钥；
3. 确认网络可达：多模态图像调用会向远端模型服务上传图片，需保证环境可访问模型 API。

4.2 运行示例

在仓库根目录下执行：

python examples/guides/nano_banana_jarvis_agent/jarvis_agent.py python examples/guides/nano_banana_jarvis_agent/img_gen_nano_banana.py

前者对hk.jpg执行地标标注，输出保存在out变量中；后者生成"落日下的未来城市天际线"图像并打印到终端。

4.3 排查要点

• check_model_supports_utilities失败：说明当前model_name不被识别为支持视觉的模型，请更换为图像多模态模型；
• 输出与预期不符：优先检查提示词中的输出约束是否完整（"Return the image only."）；
• 需要多图输入：把img="hk.jpg"改为imgs=["a.jpg", "b.jpg"]。

五、从示例走向生产：可扩展的方向

结合仓库内Agent的能力矩阵（swarms/structs/agent.py 类 docstring 第 147-277 行），这套多模态 Agent 可以按需增强：

• 多图批量：imgs=[...]一次喂多张图，可用于对比标注、多视角分析；
• Base64 直传：图片存于数据库或远端时，可读为 base64 直接传给img，无需落盘；
• 模型回退：配置fallback_models=[...]，主模型失败时自动切换（run()异常处理会调用_handle_fallback_execution）；
• 流式输出：run_stream(task, img=...)可按 token 逐字输出，适合 AR 应用中的渐进式标注反馈；
• 自主循环：将max_loops设为"auto"，让 Agent 自主规划"读图→分析→再生成"的复合流程，可组合视觉与工具调用（仓库同时提供 MCP、工具注册等扩展，见 swarms/tools 与 examples/mcp）。

结语

Nano Banana Jarvis Agent 示例以极简的两段代码，展示了 Swarms 多模态 Agent 的两个侧面：理解图像（AR 标注）与生成图像（文生图）。其背后是Agent类统一的运行入口run()、灵活的img/imgs输入设计，以及动态温度、动态上下文窗口等工程化参数。理解这份示例，就掌握了用 Swarms 快速搭建"视觉 × LLM"应用的完整方法论——无论是 AR 导航标注、图片智能审核，还是创意图像生成，都可以从这份模板直接起步。

【免费下载链接】swarmsThe Enterprise-Grade Multi-Agent Orchestration Framework. Website: https://swarms.ai项目地址: https://gitcode.com/GitHub_Trending/swar/swarms