FalClient接入Hermes Agent需五步：一、配置API密钥与启用适配器；二、修改工具路由至Fal SDK；三、映射参数字段并转换宽高比格式；四、实现异步轮询与状态重试；五、归一化响应结构为Hermes标准格式。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试在Hermes Agent中调用FalClient实现文生图功能，但图像生成失败或输出不符合预期，则可能是由于API连接未建立、认证信息错误或参数配置不匹配。以下是完成FalClient图像生成服务接入与参数精细化调整的具体操作步骤：
一、配置FalClient API密钥与基础连接
FalClient作为独立的图像生成后端，需通过环境变量注入认证凭据，并在Hermes Agent工具链中显式声明其为可用图像生成提供方。该步骤确保运行时能正确路由至Fal服务而非默认模型。
1、访问Fal.ai官网控制台，登录账户后进入Developer Settings页面；
2、点击“Create New Key”，选择Scope为“image-generation”，复制生成的API密钥（格式为sk-fal-xxxxxxxxxxxxxxxxxxxxxxxx）；
3、在Hermes Agent项目根目录下创建或编辑.env文件，添加以下行：FAL_KEY=sk-fal-xxxxxxxxxxxxxxxxxxxxxxxx；
4、确认tools/image_generation_tool.py中已启用FalClient适配器，检查是否存在fal_client_enabled: true配置项并设为true。
二、修改图像生成工具路由至FalClient
Hermes Agent默认使用OpenAI兼容接口调用图像服务，需手动切换工具分发逻辑，使image_generate_tool调用指向FalClient SDK而非原有HTTP客户端。此操作避免因协议不兼容导致的请求超时或401错误。
1、打开tools/image_generation_tool.py文件；
2、定位到import语句块，添加：from fal_client import submit, status, result；
3、查找def image_generate_tool(...)函数体，在prompt参数校验后插入条件分支：if os.getenv("FAL_KEY") and config.get("fal_client_enabled", False): return await _call_fal_client(prompt, **kwargs)；
4、在文件末尾新增异步函数_def _call_fal_client，封装submit调用与result轮询逻辑，指定app="fal-ai/flux/dev"。
三、调整FalClient专属参数映射关系
FalClient原生参数命名与Hermes Agent通用参数存在差异，需建立字段映射以保证提示词、宽高比等关键输入被正确解析。缺失映射将导致生成图像忽略aspect_ratio或guidance_scale等指令。
1、在_config.yaml_中image_generation节点下新增fal_mapping字段；
2、填入如下键值对：prompt: prompt, aspect_ratio: image_size, guidance_scale: guidance, num_images: num_outputs；
3、将aspect_ratio值转换为Fal支持格式：landscape→"1024x768"，square→"1024x1024"，portrait→"768x1024"；
4、检查num_images是否在Fal允许范围内（当前限制为1–4），超出则截断并记录warning日志。
四、启用FalClient异步轮询与状态重试机制
FalClient采用异步任务队列模式，图像生成非即时返回，需主动轮询任务状态直至完成。若缺少状态监听逻辑，工具将立即返回空结果或抛出TimeoutError。
1、在_call_fal_client函数内，使用submit启动任务后获取task_id；
2、调用status(task_id)每2秒轮询一次，最大等待时间设为180秒；
3、当status返回"IN_PROGRESS"时继续循环，返回"FAILED"时抛出RuntimeError并附带Fal错误码；
4、状态为"COMPLETED"时调用result(task_id)，提取output.url字段作为最终图像地址。
五、验证FalClient响应结构并注入Hermes标准输出格式
FalClient返回JSON结构与Hermes Agent期望的图像生成响应格式不一致，直接返回会导致前端无法解析url或缺失metadata字段，必须进行结构归一化处理。
1、从Fal result响应中提取output字段，确认其为dict且含url键；
2、构造标准响应字典：{"images": [{"url": output["url"], "seed": output.get("seed", 0), "model": "fal-ai/flux/dev"}]}；
3、若output包含"error"键，将错误信息写入log并raise ValueError(Fal generation failed: {output['error']})；
4、确保返回对象符合OpenAI函数调用规范，即具备images列表与可选的usage字段。
