hermes agent支持五种内部系统集成方案：一、rest api直连；二、消息队列异步解耦；三、gateway微服务通道；四、数据库直连桥接；五、sso统一身份认证，均通过工具注册与协议适配实现数据互通与任务协同。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望 Hermes Agent 与企业已有的内部系统（如 ERP、CRM、OA、HRM 或自建微服务）建立连接并实现数据互通与任务协同，则需通过标准化接口适配与协议桥接完成集成。以下是多种可落地的内部系统集成方案：
一、基于 REST API 的直连集成
该方式适用于内部系统已提供稳定、认证完备的 RESTful 接口，Hermes Agent 可通过内置 HTTP 工具或自定义 Tool 直接调用。其核心在于将业务逻辑封装为可注册的工具函数，并注入 Agent 的执行上下文。
1、在 tools/ 目录下新建 Python 文件，例如 erp_connector.py；
2、定义工具类，继承 hermes.tools.Tool，实现 invoke() 方法，内含对 ERP 系统 /api/v1/orders 等端点的认证请求逻辑；
3、在 tools/registry.py 中调用 register_tool(ERPConnector()) 完成注册；
4、启动 Agent 后，即可在自然语言指令中触发该工具，例如：“查询张三最近三笔采购订单”。
二、通过消息队列异步解耦集成
该方式适用于高并发、强一致性要求或存在网络隔离的场景。Hermes Agent 不直接调用内部系统，而是将请求发布至 Kafka/RabbitMQ 主题，由企业已有消费者服务完成处理并回写结果到响应队列。
1、配置 Hermes Agent 的消息客户端，使用 kafka-python 或 pika 库接入企业 MQ 集群；
2、编写 mq_publisher_tool.py，将用户意图序列化为结构化消息（含 trace_id、target_system、payload）并发送至 request topic；
3、确保企业侧已部署监听服务，能识别 Hermes 消息头并路由至对应子系统；
4、Agent 启动时订阅 response topic，通过 correlation_id 匹配原始请求并返回结果。
三、利用 Hermes Gateway 的微服务通道集成
该方式面向已采用微服务架构的企业，复用 Hermes 内置网关机制，将内部服务端点注册为受管服务，由 Hermes 统一调度与熔断，避免每个工具重复实现重试、超时、鉴权逻辑。
1、编辑 gateway/config.py，在 SERVICE_ENDPOINTS 字典中添加条目，例如 "hr-service": "https://hr-api.internal.corp:8443"；
2、创建 hr_service_tool.py，使用 hermes.gateway.request() 发起跨服务调用，自动携带服务发现与 TLS 上下文；
3、在工具初始化阶段调用 hermes.gateway.health_check("hr-service") 确保服务可达；
4、注册后，Agent 即可执行“获取李四当前部门及直属上级”等语义化指令，无需感知底层协议细节。
四、数据库直连桥接集成
该方式适用于无 API 能力但允许安全访问的遗留系统，如 Oracle ERP 或 MySQL OA。Hermes Agent 通过 SQLAlchemy 或 psycopg2 建立只读连接，执行预编译 SQL 查询，严格限制权限与查询范围。
1、在 config.yaml 中配置数据库连接串，字段包括 host、port、database、username，密码通过环境变量注入；
2、开发 db_query_tool.py，仅支持白名单内的 SELECT 语句模板，禁用子查询与 UNION；
3、所有 SQL 执行前经 sqlparse.format() 标准化并匹配正则规则 r"^SELECT\s+[\w\*,\s]+\s+FROM\s+\w+"$；
4、查询结果以表格形式返回，字段名自动映射为自然语言标签，例如 emp_name → 员工姓名。
五、单点登录与统一身份桥接集成
该方式解决 Hermes Agent 访问内部系统时的身份可信问题，避免硬编码账号或暴露凭证。通过企业已部署的 SSO 体系（如 Keycloak、CAS 或自建 OAuth2 授权服务器），使 Agent 获得短期有效的访问令牌。
1、在 Hermes 配置中启用 auth_mode: "oauth2"，指定授权地址、token 地址、client_id 与 scope；
2、首次运行时，Agent 自动打开浏览器跳转至企业登录页，用户完成认证后回调本地端口获取 code；
3、调用 hermes.auth.exchange_code_for_token() 获取 access_token 并缓存至 ~/.hermes/auth/；
4、后续所有对接内部系统的请求，均在 Authorization Header 中携带该 token，由企业网关统一校验。
