hermes agent接入rabbitmq或kafka需严格配置mq.type、连接参数、重连机制及健康检查，并通过status命令和日志验证连接状态。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试将Hermes Agent接入后端消息中间件，但任务无法正常投递或消费中断，则可能是由于消息队列连接参数配置错误或类型不匹配。以下是实现Hermes Agent与RabbitMQ及Kafka集成的具体操作路径：
一、确认消息队列类型并配置mq根节点
该步骤确保Hermes Agent识别目标中间件协议并加载对应驱动，避免因type字段误配导致连接器初始化失败。
1、打开config.yaml文件，定位到mq配置块顶层。
2、设置type字段为"rabbitmq"或"kafka"，值必须与实际部署的中间件类型严格一致，大小写敏感。
3、删除另一类型子块的全部内容（例如启用kafka时，须清空整个rabbitmq: {}结构），防止配置解析冲突。
二、配置Kafka连接参数
该步骤建立Hermes Agent与Kafka集群的初始网络连接和主题绑定，直接影响数据生产与消费链路的连通性。
1、在mq节点下进入kafka子块，确认bootstrap_servers字段为非空列表，格式为["host1:9092", "host2:9092"]，至少包含一个可连通Broker地址。
2、设置topic字段为已创建的合法主题名，例如"hermes_events"，确保该主题分区数与副本因子满足业务吞吐要求。
3、配置consumer_group字段为唯一字符串，如"hermes-agent-group-v1"，避免与其他消费者组共享offset导致消息重复或丢失。
4、检查security_protocol字段是否与集群要求匹配，明文传输设为"PLAINTEXT"，启用SSL则设为"SSL"并挂载对应truststore文件。
三、配置RabbitMQ连接参数
该步骤完成AMQP协议层认证与虚拟主机寻址，确保Hermes Agent能正确声明交换器、队列及绑定关系。
1、在mq节点下进入rabbitmq子块，确认uri字段以"amqp://"开头，且完整包含用户名、密码、主机、端口与vhost。
2、对URI中特殊字符进行URL编码，例如用户名user@domain需编码为"user%40domain"，密码pass#123需编码为"pass%23123"。
3、vhost部分需双重编码，如实际vhost为"/myapp"，则uri中应表示为"%2Fmyapp"。
4、验证connection_timeout字段为正整数（单位毫秒），建议设为5000，防止网络抖动引发连接阻塞。
四、启用消息重连与健康检查机制
该步骤保障Hermes Agent在中间件临时不可用时维持连接韧性，避免服务中断后需人工干预恢复。
1、在mq配置块中设置max_reconnect_attempts字段大于0，例如3，表示最大重试次数。
2、设置reconnect_delay_ms字段为非负整数，推荐值2000，控制两次重连尝试之间的间隔毫秒数。
3、启用health_check_enabled字段并设为true，使Agent周期性发送心跳帧验证通道活性。
4、检查health_check_interval_ms字段是否合理，建议设为30000（30秒），避免高频探测加重中间件负载。
五、验证集成状态与日志输出
该步骤通过运行时反馈确认配置已生效，定位连接失败的具体环节而非仅依赖启动成功提示。
1、启动Hermes Agent后，执行./hermes status --service mq命令，检查输出中status字段是否为"connected"。
2、查看logs/hermes-agent.log文件，搜索关键字"Connected to Kafka"或"RabbitMQ connection established"。
3、若出现AuthenticationFailure异常，立即核对uri中的用户名密码或kafka的sasl.jaas.config配置项。
4、若日志持续打印“Failed to resolve broker host”，则检查host域名是否可在容器/服务器内通过nslookup解析，或改用IP直连。
