Why HagiCode Chose Hermes as Its Integrated Agent Core

19 mars 2026

Why HagiCode Chose Hermes as Its Integrated Agent Core

When building an AI-assisted coding platform, choosing the right Agent core directly determines the upper limit of the system’s capabilities. Some things simply cannot be forced; pick the wrong framework, and no amount of effort will make it feel right. This article shares the thinking behind HagiCode’s technical selection and our hands-on experience integrating Hermes Agent.

Background

When building an AI-assisted coding product, one of the hardest parts is choosing the underlying Agent framework. There are actually quite a few options on the market, but some are too limited in functionality, some are overly complex to deploy, and others simply do not scale well enough. What we needed was a solution that could run on a $5 VPS while also being able to connect to a GPU cluster. That requirement may not sound extreme, but it is enough to scare plenty of teams away.

In practice, many so-called “all-in-one Agents” either only run in the cloud or require absurdly high local deployment costs. After spending two weeks researching different approaches, we made a bold decision: rebuild the entire Agent core around Hermes as the underlying engine for our integrated Agent.

Everything that followed may simply have been fate.

About HagiCode

The approach shared in this article comes from real-world experience in the HagiCode project. HagiCode is an AI-assisted coding platform that provides developers with an intelligent coding assistant through a VSCode extension, a desktop client, and web services. You may have used similar tools before and felt they were just missing that final touch; we understand that feeling well.

GitHub: github.com/HagiCode-org/site
Official website: hagicode.com

Why HagiCode Needs Hermes

Before diving into Hermes itself, it helps to explain why HagiCode needed something like it in the first place. Things rarely work exactly the way you want, so you need a practical reason to commit to a technical direction.

As an AI coding assistant, HagiCode needs to support several usage scenarios at the same time:

Local development environments: developers want to run it on their own machines so data never leaves the local environment. These days, data security is never a trivial concern.
Team collaboration environments: small teams should be able to share an Agent deployment running on a server. Saving money matters, and everyone has limits.
Elastic cloud expansion: when handling complex tasks, the system should automatically scale out to a GPU cluster. It is always better to be prepared.

This “we want everything at once” requirement is what led us to Hermes. Whether it was the perfect choice, I cannot say for sure, but at the time we did not see a better option.

What Is Hermes Agent

Hermes Agent is an autonomous AI Agent created by Nous Research. Some readers may not be familiar with Nous Research; they are the lab behind open-source large models such as Hermes, Nomos, and Psyché. They have built many excellent things, even if they are still more underappreciated than they deserve.

Unlike traditional IDE coding assistants or simple API chat wrappers, Hermes has a defining trait: the longer it runs, the more capable it becomes. It is not designed to complete a task once and stop; it keeps learning and accumulating experience over long-running operation. In that sense, it feels a little like a person.

Core Features

Several of Hermes’s core capabilities happen to align very closely with HagiCode’s needs.

This means HagiCode can choose the most suitable deployment model based on each user’s scenario: individuals run it locally, teams deploy it on servers, and complex tasks use GPU resources. One codebase handles all of it. In a world this busy, saving one layer of complexity is already a win.

Multi-platform messaging gateway Hermes natively supports Telegram, Discord, Slack, WhatsApp, and more. For HagiCode, this means we can support AI assistants on those channels much more easily in the future. More paths forward are always welcome.

Rich tool system Hermes comes with 40+ built-in tools and supports MCP (Model Context Protocol) extensions. This is essential for a coding assistant: executing shell commands, working with the file system, and calling Git all depend on tool support. An Agent without tools is like a bird without wings.

Cross-session memory Hermes includes a persistent memory system and uses FTS5 full-text search to recall historical conversations. That allows the Agent to remember prior context instead of “losing its memory” every time. Sometimes people wish they could forget things that easily, but reality is usually less generous.

How HagiCode Integrates Hermes

Now that the “why” is clear, let us look at the “how.” Once something makes sense in theory, the next step is to build it.

Provider Layer Abstraction

In HagiCode’s architecture, all AI Providers implement a unified IAIProvider interface:

public sealed class HermesCliProvider : IAIProvider, IVersionedAIProvider
{
    public ProviderCapabilities Capabilities { get; } = new ProviderCapabilities
    {
        SupportsStreaming = true,   // Supports streaming output
        SupportsTools = true,       // Supports tool invocation
        SupportsSystemMessages = true, // Supports system prompts
        SupportsArtifacts = false
    };
}

This abstraction layer allows HagiCode to switch seamlessly between different AI Providers. Whether the backend is OpenAI, Claude, or Hermes, the upper-layer calling pattern stays exactly the same. In plain terms, it keeps things simple.

ACP Communication Protocol

Hermes communicates through ACP (Agent Communication Protocol). This protocol is designed specifically for Agent communication, and its main methods include:

Method	Description
`initialize`	Initialize the connection and obtain the protocol version and client capabilities
`authenticate`	Handle authentication and support multiple authentication methods
`session/new`	Create a new session and configure the working directory and MCP servers
`session/prompt`	Send a prompt and receive a response

HagiCode implements the ACP transport layer through StdioAcpTransport, launching a Hermes subprocess and communicating with it over standard input and output. It may sound complicated, but in practice it is manageable as long as you have enough patience.

Configuration Management

Configuration is managed through the HermesPlatformConfiguration class:

public sealed class HermesPlatformConfiguration : IAcpPlatformConfiguration
{
    public string ExecutablePath { get; set; } = "hermes";
    public string Arguments { get; set; } = "acp";
    public int StartupTimeoutMs { get; set; } = 5000;
    public string ClientName { get; set; } = "HagiCode";
    public HermesAuthenticationConfiguration Authentication { get; set; }
    public HermesSessionDefaultsConfiguration SessionDefaults { get; set; }
}

Configure Hermes in appsettings.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"
      }
    }
  }
}

Configuration often looks simple on paper, but getting every detail right still takes real effort.

Orleans Distributed Architecture

HagiCode uses Orleans to build its distributed system, and the Hermes integration is implemented through the following components:

HermesGrain: An Orleans Grain implementation that handles session execution
HermesPlatformConfiguration: Platform-specific configuration
HermesAcpSessionAdapter: ACP session adapter
HermesConsole: A dedicated validation console

The name Orleans does have a certain charm to it. Even if this Orleans has nothing to do with the legendary city, a good name never hurts.

End-to-End Execution Flow

The following is the core execution logic of the Hermes Provider:

private async IAsyncEnumerable<AIStreamingChunk> StreamCoreAsync(
    AIRequest request,
    string? embeddedCommandPrompt,
    [EnumeratorCancellation] CancellationToken cancellationToken)
{
    // 1. Create transport layer and launch Hermes subprocess
    await using var transport = new StdioAcpTransport(
        platformConfiguration.GetExecutablePath(),
        platformConfiguration.GetArguments(),
        platformConfiguration.GetEnvironmentVariables(),
        platformConfiguration.GetStartupTimeout(),
        _loggerFactory.CreateLogger<StdioAcpTransport>());
    await transport.ConnectAsync(cancellationToken);

    // 2. Initialize and obtain protocol version and authentication methods
    var initializeResult = await SendHermesRequestAsync(
        transport, nextRequestId++, "initialize",
        BuildInitializeParameters(platformConfiguration), cancellationToken);

    // 3. Handle authentication
    var authMethods = ParseAuthMethods(initializeResult);
    if (!isAuthenticated)
    {
        var methodId = platformConfiguration.Authentication.ResolveMethodId(authMethods);
        await SendHermesRequestAsync(transport, nextRequestId++, "authenticate", ...);
    }

    // 4. Create session
    var newSessionResult = await SendHermesRequestAsync(
        transport, nextRequestId++, "session/new",
        BuildNewSessionParameters(platformConfiguration, workingDirectory, model), cancellationToken);
    var sessionId = ParseSessionId(newSessionResult);

    // 5. Execute prompt and collect streaming responses
    await foreach (var payload in transport.ReceiveMessagesAsync(cancellationToken))
    {
        // Handle session/update notifications and convert them into streaming chunks
        if (TryParseSessionNotification(root, out var notification))
        {
            if (_responseMapper.TryConvertToStreamingChunk(notification, out var chunk))
            {
                yield return chunk;
            }
        }
    }
}

With code, the details eventually become familiar. What matters most is the overall approach.

Health Checks

To ensure Hermes remains available, HagiCode implements a health check mechanism:

public async Task<ProviderTestResult> PingAsync(CancellationToken cancellationToken = default)
{
    var response = await ExecuteAsync(
        new AIRequest
        {
            Prompt = "Reply with exactly PONG.",
            CessionId = null,
            AllowedTools = Array.Empty<string>(),
            WorkingDirectory = ResolveWorkingDirectory(null)
        },
        cancellationToken);

    var success = string.Equals(response.Content.Trim(), "PONG", StringComparison.OrdinalIgnoreCase);
    return new ProviderTestResult
    {
        ProviderName = Name,
        Success = success,
        ResponseTimeMs = stopwatch.ElapsedMilliseconds,
        ErrorMessage = success ? null : $"Unexpected Hermes ping response: '{response.Content}'."
    };
}

That is roughly what a “health check” looks like here. In some ways, people are not so different: it helps to check in from time to time, even if no one tells us exactly what to look for.

Practical Considerations

There are a few pitfalls worth understanding before integrating Hermes. Everyone steps into a few traps sooner or later.

Authentication Method Configuration

Hermes supports multiple authentication methods, including API keys and tokens, so you need to choose based on the actual deployment scenario. Misconfiguration can cause connection failures, and the resulting error messages are not always intuitive. Sometimes the reported error is far away from the real root cause, which means slow and careful debugging is unavoidable.

MCP Server Configuration

When creating a session, you can configure a list of MCP servers so Hermes can call external tools. But keep the following points in mind:

MCP server addresses must be reachable
Timeouts must be configured reasonably
The system needs degradation handling when a server is unavailable

In practice, defensive thinking matters more than people expect.

Working Directory Management

Each session must specify a working directory so Hermes can access project files correctly. In multi-project scenarios, the working directory needs to switch dynamically. It sounds straightforward, but there are more edge cases than you might think.

Response Aggregation

Hermes responses may be split across session/update notifications and the final result, so they must be merged correctly. Otherwise, content may be lost.

Error Handling Strategy

Runtime errors should be returned explicitly instead of silently falling back to another Provider. That way, users know the issue came from Hermes rather than wondering why the system suddenly switched models behind the scenes.

Conclusion

HagiCode’s decision to use Hermes as its integrated Agent core was not a casual impulse. It was a careful choice based on practical requirements and the technical characteristics of the framework. Whether it proves to be the perfect long-term answer is still too early to say, but so far it has been serving us well.

Hermes gives HagiCode the flexibility to adapt to a wide range of scenarios. Its powerful tool system and MCP support allow the AI assistant to do real work, while the ACP protocol and Provider abstraction layer keep the integration process clear and controllable.

If you are choosing an Agent framework for your own AI project, I hope this article offers a useful reference. Picking the right underlying architecture can make everything that follows much easier.

If This Article Helped You

Give us a star on GitHub: github.com/HagiCode-org/site
Visit the official website to learn more: hagicode.com
Watch the 30-minute hands-on demo: www.bilibili.com/video/BV1pirZBuEzq/
One-click installation experience: docs.hagicode.com/installation/docker-compose
Quick install for the Desktop client: hagicode.com/desktop/
Public beta has started; you are welcome to install and try it
Official Hermes documentation

Copyright Notice

Thank you for reading. If you found this article useful, you are welcome to support it with a like, bookmark, or share. This content was created with AI-assisted collaboration, and the final content was reviewed and confirmed by the author.

Author: newbe36524
Original article: https://docs.hagicode.com/blog/2026-03-19-hagicode-hermes-agent-core/
Copyright notice: Unless otherwise stated, all articles on this blog are licensed under BY-NC-SA. Please indicate the source when reprinting.