Hermes Agent 集成实践从协议到生产分享 HagiCode 集成 Hermes Agent 的完整实践包括 ACP 协议适配、会话池管理、前后端契约同步等核心经验。背景在构建 AI 辅助编码平台 HagiCode 的过程中团队需要集成一个既能在本地运行又能扩展到云端的 Agent 框架。经过调研Nous Research 的 Hermes Agent 被选为综合 Agent 的底层引擎。其实选型这事儿说难也不难说简单也不简单。毕竟市面上能打的 Agent 框架也不少只是 Hermes 那个 ACP 协议和工具系统确实有点东西刚好契合 HagiCode 既要又要的需求场景——本地开发、团队协作和云端扩展。但要把 Hermes 真正融入生产系统还需要解决一系列工程问题这可不是闹着玩的。HagiCode 的技术栈基于 Orleans 构建分布式系统前端使用 React TypeScript。集成 Hermes 需要在保持现有架构统一性的前提下让 Hermes 成为与 ClaudeCode、OpenCode 等并行的一等公民执行器。说起来容易做起来嘛也就那样吧。本文分享我们在 HagiCode 项目中集成 Hermes Agent 的实践经验希望能给面临类似需求的团队提供参考。毕竟踩过的坑没必要让别人再踩一遍。关于 HagiCode本文分享的方案来自我们在 HagiCode (https://hagicode.com) 项目中的实践经验。HagiCode 是一个 AI 驱动的编码辅助平台支持多种 AI Provider 的统一接入和管理。在集成 Hermes Agent 的过程中我们设计了一套通用的 Provider 抽象层使得新的 Agent 类型可以无缝接入现有系统。如果你对 HagiCode 感兴趣欢迎访问 GitHub (https://github.com/HagiCode-org/site) 了解更多。多个人看多份力量罢了。架构设计分层设计思路HagiCode 的 Hermes 集成采用了清晰的分层架构每层各司其职后端核心层HermesCliProvider: 实现IAIProvider接口作为统一的 AI Provider 入口HermesPlatformConfiguration: 管理 Hermes 可执行文件路径、参数、认证等配置ICliProviderHermesOptions: HagiCode.Libs 提供的底层 CLI 抽象处理子进程生命周期传输层StdioAcpTransport: 通过标准输入输出与 Hermes ACP 子进程通信ACP 协议方法initialize、authenticate、session/new、session/prompt运行时层HermesGrain: Orleans Grain 实现处理分布式会话执行CliAcpSessionPool: 会话池复用 ACP 子进程避免频繁启动开销前端层ExecutorAvatar: Hermes 视觉标识和图标executorTypeAdapter: Provider 类型映射逻辑SignalR 实时消息传递保持 Hermes 身份在消息流中的一致性这种分层设计使得各层可以独立演进比如未来要添加新的传输方式如 WebSocket只需修改传输层即可。毕竟谁愿意因为改一个传输方式就把整个系统都翻一遍呢多累啊。统一接口抽象所有 AI Provider 都实现IAIProvider接口这是 HagiCode 架构的核心设计csharp public interfaceIAIProvider { string Name { get; } ProviderCapabilities Capabilities { get; } IAsyncEnumerableAIStreamingChunk StreamAsync( AIRequest request, CancellationToken cancellationToken default); TaskAIResponse ExecuteAsync( AIRequest request, CancellationToken cancellationToken default); }HermesCliProvider实现了这个接口与ClaudeCodeProvider、OpenCodeProvider等处于平等地位。这种设计带来的好处可替换性: 切换 Provider 不影响上层业务逻辑可测试性: 可以轻松 Mock Provider 进行单元测试可扩展性: 新增 Provider 只需实现接口即可说到底接口这东西就像规矩一样。有了规矩大家才能和谐共处各自发挥所长互不干扰。这难道不是一种美吗核心实现Provider 层实现HermesCliProvider是整个集成的核心它负责协调各个组件完成一次 AI 调用csharp public sealedclassHermesCliProvider : IAIProvider, IVersionedAIProvider { privatereadonly ICliProviderLibsHermesOptions _provider; privatereadonly ConcurrentDictionarystring, string _sessionBindings; public ProviderCapabilities Capabilities { get; } new() { SupportsStreaming true, SupportsTools true, SupportsSystemMessages true, SupportsArtifacts false }; publicasync IAsyncEnumerableAIStreamingChunk StreamAsync( AIRequest request, [EnumeratorCancellation] CancellationToken cancellationToken default) { // 1. 解析会话绑定 key var bindingKey ResolveBindingKey(request.CessionId); // 2. 通过会话池获取或创建 Hermes 会话 var options new HermesOptions { ExecutablePath _platformConfiguration.ExecutablePath, Arguments _platformConfiguration.Arguments, SessionId _sessionBindings.TryGetValue(bindingKey, outvar sessionId) ? sessionId : null, WorkingDirectory request.WorkingDirectory, Model request.Model }; // 3. 执行并收集流式响应 awaitforeach (var message in _provider.ExecuteAsync(options, request.Prompt, cancellationToken)) { // 4. 映射 ACP 消息到 AIStreamingChunk if (_responseMapper.TryConvertToStreamingChunk(message, outvar chunk)) { yieldreturn chunk; } } } }这里有几个关键设计点会话绑定: 通过CessionId将多个请求绑定到同一个 Hermes 子进程实现多轮对话的上下文连续性响应映射: 将 Hermes ACP 消息格式转换为统一的AIStreamingChunk格式流式处理: 使用IAsyncEnumerable支持真正的流式响应其实会话绑定这事儿就像人和人之间的关系一样。一旦建立了联系后续的交流就有了上下文不用每次都从头开始。只是这关系要维护好不然断了就断了。ACP 协议适配Hermes 使用 ACPAgent Communication Protocol协议与传统的 HTTP API 不同。ACP 是基于标准输入输出的协议有几个特点启动标记: Hermes 进程启动后会输出//ready标记动态认证: 认证方法不是固定的需要通过协议协商会话复用: 通过SessionId复用已建立的会话响应分散: 完整响应可能分散在多个session/update通知中HagiCode 通过StdioAcpTransport处理这些特性csharp public classStdioAcpTransport { publicasync Task InitializeAsync(CancellationToken cancellationToken) { // 等待 //ready 标记 var readyLine await _outputReader.ReadLineAsync(cancellationToken); if (readyLine ! //ready) { thrownew InvalidOperationException(Hermes did not send ready signal); } // 发送 initialize 请求 await SendRequestAsync(new { jsonrpc 2.0, id 1, method initialize, params new { protocolVersion 2024-11-05, capabilities new { }, clientInfo new { name HagiCode, version 1.0.0 } } }, cancellationToken); } }协议这东西就像人与人之间的默契。有了默契交流就会顺畅很多。只是建立默契需要时间磨合嘛谁都免不了。会话池管理频繁启动 Hermes 子进程的开销很大因此我们实现了会话池机制csharp services.AddSingleton(static _ { var registry new CliProviderPoolConfigurationRegistry(); registry.Register(hermes, new CliPoolSettings { MaxActiveSessions 50, IdleTimeout TimeSpan.FromMinutes(10) }); return registry; });会话池的关键参数MaxActiveSessions: 控制并发上限避免资源耗尽IdleTimeout: 空闲超时平衡启动成本和内存占用实践中我们发现空闲超时设置太短会导致频繁重启设置太长会占用内存并发上限需要根据实际负载调整过大可能导致系统卡顿需要监控会话池的使用情况以便及时调整参数这就好比人生中的许多选择太激进容易出问题太保守又错失机会。找个平衡点罢了。前端集成类型映射前端需要正确识别 Hermes Provider 并显示对应的视觉元素typescript // executorTypeAdapter.ts exportconst resolveExecutorVisualTypeFromProviderType ( providerType: PCode_Models_AIProviderType | null | undefined ): ExecutorVisualType { switch (providerType) { casePCode_Models_AIProviderType.HERMES_CLI: returnHermes; default: returnUnknown; } };视觉呈现Hermes 有专属的图标和颜色标识typescript // ExecutorAvatar.tsx constrenderExecutorGlyph (executorType: ExecutorVisualType, iconSize: number) { switch (executorType) { caseHermes: return ( svgviewBox0 0 24 24fillnoneclassNameh-4 w-4 rectx4y4width16height16rx4fillcurrentColoropacity0.16 / pathdM8 7v10M16 7v10M8 12h8strokecurrentColorstrokeWidth2strokeLinecapround / /svg ); default: returnDefaultAvatar /; } };毕竟美的东西也要有美的呈现。只是这美要被人看见还得靠前端同学的努力。契约同步前后端通过 OpenAPI 生成保持契约一致。后端定义了AIProviderType枚举csharp public enum AIProviderType { Unknown, ClaudeCode, OpenCode, HermesCli // 新增 }前端通过 OpenAPI 生成对应的 TypeScript 类型确保枚举值一致。这是避免前端显示 “Unknown” 的关键。契约这东西就像承诺一样。说好了就要做到不然就会出现Unknown这种尴尬的局面。配置管理Hermes 的配置通过appsettings.json管理json { Providers:{ HermesCli:{ ExecutablePath:hermes, Arguments:acp, StartupTimeoutMs:10000, ClientName:HagiCode, Authentication:{ PreferredMethodId:api-key, MethodInfo:{ api-key:your-api-key-here } }, SessionDefaults:{ Model:claude-sonnet-4-20250514, ModeId:default } } } }这种配置驱动的设计带来了灵活性可以覆盖可执行文件路径方便开发测试可以自定义启动参数适配不同版本的 Hermes可以配置认证信息支持多种认证方式配置这东西就像人生的选择题。给足了选项总能找到适合自己的那一个。只是有时候选项太多也会让人犯选择困难症。实践经验健康检查实现一个可靠的 Provider 需要完善的健康检查csharp public async TaskProviderTestResult PingAsync(CancellationToken cancellationToken default) { var response await ExecuteAsync(new AIRequest { Prompt Reply with exactly PONG., CessionId null, AllowedTools Array.Emptystring(), WorkingDirectory ResolveWorkingDirectory(null) }, cancellationToken); var success string.Equals(response.Content.Trim(), PONG, StringComparison.OrdinalIgnoreCase); returnnew ProviderTestResult { ProviderName Name, Success success, ResponseTimeMs stopwatch.ElapsedMilliseconds, ErrorMessage success ? null : $Unexpected Hermes ping response: {response.Content}. }; }健康检查需要注意使用简单的测试用例避免复杂场景设置合理的超时时间记录响应时间便于性能分析就像人需要体检一样系统也需要健康检查。早发现早治疗省得到时候出大问题。验证工具HagiCode 提供专用控制台用于验证 Hermes 集成bash # 基础验证 HagiCode.Libs.Hermes.Console --test-provider # 完整套件含仓库分析 HagiCode.Libs.Hermes.Console --test-provider-full --repo . # 自定义可执行文件 HagiCode.Libs.Hermes.Console --test-provider-full --executable /path/to/hermes这个工具在开发过程中非常有用可以快速验证集成是否正确。毕竟谁愿意在发现问题的时候才想起来去测试呢常见问题处理认证失败检查Authentication.PreferredMethodId与 Hermes 实际支持的认证方法是否匹配确认认证信息格式正确API Key、Bearer Token 等会话超时增加StartupTimeoutMs值检查 MCP 服务器可达性查看系统资源使用情况响应不完整确保正确聚合session/update通知和最终结果检查流式处理的取消逻辑验证错误处理是否完整前端显示 Unknown确认 OpenAPI 生成已包含HermesCli枚举值检查类型映射是否正确清除浏览器缓存重新生成类型问题嘛总会有的。只是遇到问题的时候别慌慢慢找原因总能解决的。毕竟办法总比困难多。性能优化建议使用会话池: 复用 ACP 子进程减少启动开销合理设置超时: 平衡内存和启动成本复用会话 ID: 批量任务使用同一个CessionId按需配置 MCP: 避免不必要的工具调用性能这东西就像生活中的效率。做对了事半功倍做错了事倍功半。只是找到那个对的点需要经验和运气。总结集成 Hermes Agent 到生产系统需要考虑多个层面的问题架构层面: 设计统一的 Provider 接口实现可替换的组件架构协议层面: 正确处理 ACP 协议的特殊性如启动标记、动态认证等性能层面: 通过会话池复用资源平衡启动成本和内存占用前端层面: 确保契约同步提供一致的视觉体验HagiCode 的实践表明通过良好的分层设计和配置驱动可以将复杂的 Agent 系统无缝集成到现有架构中。其实这些道理说起来都挺简单的只是真正做起来的时候总会遇到各种各样的问题。不过没关系问题解决了就是经验解决不了就是教训都是有价值的东西。美的事物或人不一定要占有只要她还是美的自己好好看着她的美就好了。技术也是如此只要能让系统变得更好用什么框架、什么协议其实都没那么重要…参考资料HagiCode 项目地址 (https://github.com/HagiCode-org/site)HagiCode 官网 (https://hagicode.com)Hermes Agent 文档 (https://hermes.nousresearch.com/)ACP 协议规范 (https://github.com/NousResearch/Hermes/blob/main/docs/acp.md)HagiCode 安装指南 (https://docs.hagicode.com/installation/docker-compose)HagiCode Desktop (https://hagicode.com/desktop/)原文与版权说明感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。本文作者: newbe36524 (https://www.newbe.pro)原文链接: https://docs.hagicode.com/go?platformwechattarget%2Fblog%2F2026-04-14-hermes-agent-integration-practice%2F (https://docs.hagicode.com/go?platformwechattarget%2Fblog%2F2026-04-14-hermes-agent-integration-practice%2F)版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!