Hermes Agent API提供三种调用方式：一、启动REST API服务（hermes api serve），通过curl调用/v1/chat/completions；二、直连Gateway WebSocket，连接ws://127.0.0.1:8080/ws并收发JSON消息帧；三、使用ACP本地Unix Socket（/tmp/hermes-acp.sock），以二进制协议通信。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您需要与 Hermes Agent 进行程序化交互，但尚未建立可用的通信通道，则可能是由于未启用对应协议服务或请求格式不匹配。以下是调用 Hermes Agent API 的三种独立可行方式：
一、启用并调用内置 REST API 服务
该方式通过 HTTP 协议暴露标准化的 OpenAI 兼容接口，适用于脚本调用、轻量级后端集成及调试验证场景，无需额外网关组件。
1、确保已完成 Hermes Agent 的完整安装，并处于激活虚拟环境状态。
2、执行命令启动 API 服务：hermes api serve --host 0.0.0.0 --port 8000。
3、确认终端输出包含"API server started on http://0.0.0.0:8000"字样，表示服务已就绪。
4、使用 curl 向 POST /v1/chat/completions 发送 JSON 请求，示例结构如下：
curl -X POST http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "列出当前目录文件"}], "session_id": "test-session"}'
二、通过 Gateway WebSocket 协议直连
该方式绕过 HTTP 层，直接复用 Hermes Gateway 启动的 WebSocket 服务，适用于需低延迟响应、双向实时事件流（如前端聊天界面）的集成需求。
1、先运行hermes gateway run启动网关进程。
2、查看日志中类似"WebSocket server listening on ws://127.0.0.1:8080/ws"的地址信息。
3、使用任意 WebSocket 客户端（如 Python 的 websockets 库）连接该地址。
4、发送标准化 JSON 消息帧，必须包含字段："type": "message"、"session_id" 和 "content"。
5、接收响应时注意解析 "event": "response_chunk" 或 "event": "response_complete" 类型的消息。
三、调用 ACP（Agent Control Protocol）本地 Unix Socket
该方式面向同机高性能集成场景，如嵌入 Shell 脚本或 CI/CD 流水线，采用 Unix Domain Socket 通信，规避网络栈开销，支持完整生命周期控制与工具调用透传。
1、确认 Hermes Agent 已以 ACP 模式启动，通常需在配置中显式启用 agent_control_protocol: true。
2、检查运行时生成的 Unix Socket 路径，默认为 /tmp/hermes-acp.sock。
3、使用支持 Unix Socket 的客户端（如 socat 或自定义 Python socket.socket(AF_UNIX)）连接该路径。
4、发送二进制协议帧，头部需包含长度前缀与指令类型码，有效载荷为序列化的 JSON 控制指令。
5、读取返回的二进制响应帧，按协议规范解析状态码、会话元数据与工具执行结果。
