调用Hermes Agent API需依次完成五步：一、确认服务启动并监听正确端口；二、用curl发起OpenAI格式请求；三、用Python requests程序化调用；四、用hermes_cli工具封装调用；五、通过Swagger UI可视化调用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试调用Hermes Agent的API接口，但请求失败或返回空响应，则可能是由于认证配置缺失、端点地址错误或请求格式不符合OpenAI风格规范。以下是调用Hermes Agent API的具体方法：
一、确认基础服务已启动并监听正确端口
Hermes Agent默认通过本地HTTP服务器暴露API，其行为与OpenAI兼容接口一致，需确保服务进程正在运行且绑定到预期地址。该步骤是所有后续调用的前提，避免因服务未就绪导致连接被拒绝。
1、检查Hermes Agent是否已在后台运行：执行ps aux | grep hermes，确认存在hermes-cli serve或gateway/run.py相关进程。
2、验证API服务端口状态：运行curl -v http://localhost:8000/health，若返回{"status":"healthy"}，说明服务已就绪；若提示Connection refused，则需先执行hermes serve启动服务。
3、确认实际监听地址：查看environments/default.yaml中gateway.host与gateway.port字段，典型值为host: "0.0.0.0"与port: 8000，不可直接假设为127.0.0.1:8000。
二、使用curl命令行工具发起标准OpenAI格式请求
该方法适用于快速验证、脚本集成及CI/CD环境，无需额外依赖，直接复用Hermes Agent对OpenAI-style endpoint的原生支持能力。
1、构造含认证头的POST请求：确保Authorization头值为Bearer <strong><span>your-api-key-here</span></strong>，其中密钥需与cli-config.yaml中api_key字段一致。
2、设置Content-Type为application/json，并在请求体中按OpenAI规范提供model、messages字段，例如：{"model":"llama3","messages":[{"role":"user","content":"Hello"}]}。
3、执行完整调用命令：curl -X POST "http://localhost:8000/v1/chat/completions" -H "Authorization: Bearer <strong><span>sk-xxx</span></strong>" -H "Content-Type: application/json" -d '{"model":"llama3","messages":[{"role":"user","content":"Hello"}]}'。
三、通过Python requests库进行程序化调用
该方式适合嵌入至自动化工作流、数据处理管道或自定义前端应用中，支持会话管理、异常重试与响应解析等高级控制。
1、安装requests库（如未安装）：pip install requests。
2、编写调用脚本，显式指定base_url为<strong><span>http://localhost:8000/v1</span></strong>，该URL必须与cli-config.yaml中provider.base_url完全匹配。
3、构建请求头字典，包含Authorization与Content-Type，其中API密钥须从环境变量读取（如os.getenv("HERMES_API_KEY")），避免硬编码。
4、使用requests.post()发送JSON载荷，捕获response.status_code并检查是否为200，非200时打印response.text用于调试。
四、利用hermes_cli命令行工具封装调用
该方法屏蔽底层HTTP细节，由官方CLI自动注入认证信息与默认参数，适合日常调试与交互式测试，降低出错概率。
1、确保已执行hermes setup完成初始配置，且cli-config.yaml中provider.api_key字段非空。
2、运行hermes chat --model llama3 --message "What is the capital of France?"，CLI将自动构造合规请求并输出响应正文。
3、如需查看原始HTTP交互过程，添加--verbose标志：hermes chat --verbose --model llama3 --message "test"，终端将打印完整请求头与响应体。
五、通过Flask-RESTX Swagger UI界面可视化调用
该方式提供图形化表单输入、参数自动补全与实时响应预览，特别适合新用户理解各API端点的功能边界与参数约束。
1、确认已启用Swagger支持：检查requirements.txt含flask-restx==1.1.0与swagger-ui-bundle==0.0.9，且tools/web_tools.py中已初始化Api()实例。
2、启动服务后访问<strong><span>http://localhost:8000/swagger</span></strong>，页面加载完成后可见所有已注册端点（如/v1/chat/completions）。
3、点击目标端点右侧的“Try it out”按钮，在Parameters区域填入model与messages，点击“Execute”，界面下方将显示请求cURL命令与响应JSON结构。
