client.gopackage main
import (
"context"
"sync"
acp "github.com/coder/acp-go-sdk"
harnessruntime "github.com/kagent-dev/kagent/go/harness/runtime"
)
type hermesACPClient struct {
mu sync.RWMutex
sink harnessruntime.EventSink
toolNames map[string]string
}
func newHermesACPClient() *hermesACPClient {
return &hermesACPClient{toolNames: map[string]string{}}
}
func (c *hermesACPClient) setSink(sink harnessruntime.EventSink) {
c.mu.Lock()
defer c.mu.Unlock()
c.sink = sink
}
func (c *hermesACPClient) SessionUpdate(_ context.Context, notification acp.SessionNotification) error {
c.mu.Lock()
defer c.mu.Unlock()
if c.sink == nil {
return nil
}
update := notification.Update
switch {
case update.AgentMessageChunk != nil && update.AgentMessageChunk.Content.Text != nil:
return c.sink.TextDelta(harnessruntime.TextDelta{Text: update.AgentMessageChunk.Content.Text.Text})
case update.ToolCall != nil:
name := update.ToolCall.Title
id := string(update.ToolCall.ToolCallId)
c.toolNames[id] = name
arguments, _ := update.ToolCall.RawInput.(map[string]any)
return c.sink.ToolCall(harnessruntime.ToolCall{ID: id, Name: name, Arguments: arguments})
case update.ToolCallUpdate != nil && update.ToolCallUpdate.Status != nil:
status := *update.ToolCallUpdate.Status
if status != acp.ToolCallStatusCompleted && status != acp.ToolCallStatusFailed {
return nil
}
id := string(update.ToolCallUpdate.ToolCallId)
return c.sink.ToolResult(harnessruntime.ToolResult{
ID: id, Name: c.toolNames[id], Result: update.ToolCallUpdate.RawOutput,
IsError: status == acp.ToolCallStatusFailed,
})
default:
return nil
}
}
func (c *hermesACPClient) RequestPermission(_ context.Context, request acp.RequestPermissionRequest) (acp.RequestPermissionResponse, error) {
for _, option := range request.Options {
if option.Kind == acp.PermissionOptionKindRejectOnce || option.Kind == acp.PermissionOptionKindRejectAlways {
return acp.RequestPermissionResponse{Outcome: acp.RequestPermissionOutcome{
Selected: &acp.RequestPermissionOutcomeSelected{Outcome: "selected", OptionId: option.OptionId},
}}, nil
}
}
return acp.RequestPermissionResponse{Outcome: acp.RequestPermissionOutcome{
Cancelled: &acp.RequestPermissionOutcomeCancelled{Outcome: "cancelled"},
}}, nil
}
func (c *hermesACPClient) ReadTextFile(context.Context, acp.ReadTextFileRequest) (acp.ReadTextFileResponse, error) {
return acp.ReadTextFileResponse{}, acp.NewMethodNotFound("fs/read_text_file")
}
func (c *hermesACPClient) WriteTextFile(context.Context, acp.WriteTextFileRequest) (acp.WriteTextFileResponse, error) {
return acp.WriteTextFileResponse{}, acp.NewMethodNotFound("fs/write_text_file")
}
func (c *hermesACPClient) CreateTerminal(context.Context, acp.CreateTerminalRequest) (acp.CreateTerminalResponse, error) {
return acp.CreateTerminalResponse{}, acp.NewMethodNotFound("terminal/create")
}
func (c *hermesACPClient) KillTerminal(context.Context, acp.KillTerminalRequest) (acp.KillTerminalResponse, error) {
return acp.KillTerminalResponse{}, acp.NewMethodNotFound("terminal/kill")
}
func (c *hermesACPClient) TerminalOutput(context.Context, acp.TerminalOutputRequest) (acp.TerminalOutputResponse, error) {
return acp.TerminalOutputResponse{}, acp.NewMethodNotFound("terminal/output")
}
func (c *hermesACPClient) ReleaseTerminal(context.Context, acp.ReleaseTerminalRequest) (acp.ReleaseTerminalResponse, error) {
return acp.ReleaseTerminalResponse{}, acp.NewMethodNotFound("terminal/release")
}
func (c *hermesACPClient) WaitForTerminalExit(context.Context, acp.WaitForTerminalExitRequest) (acp.WaitForTerminalExitResponse, error) {
return acp.WaitForTerminalExitResponse{}, acp.NewMethodNotFound("terminal/wait_for_exit")
}
var _ acp.Client = (*hermesACPClient)(nil)
client_test.gopackage main
import (
"context"
"testing"
acp "github.com/coder/acp-go-sdk"
harnessruntime "github.com/kagent-dev/kagent/go/harness/runtime"
)
type recordingSink struct {
text string
call harnessruntime.ToolCall
result harnessruntime.ToolResult
}
func (*recordingSink) SessionStarted(harnessruntime.SessionStarted) error { return nil }
func (s *recordingSink) TextDelta(delta harnessruntime.TextDelta) error {
s.text += delta.Text
return nil
}
func (s *recordingSink) ToolCall(call harnessruntime.ToolCall) error { s.call = call; return nil }
func (s *recordingSink) ToolResult(result harnessruntime.ToolResult) error {
s.result = result
return nil
}
func (*recordingSink) ModelCall(harnessruntime.ModelCall) {}
func TestHermesACPClientForwardsText(t *testing.T) {
t.Parallel()
sink := &recordingSink{}
client := newHermesACPClient()
client.setSink(sink)
err := client.SessionUpdate(context.Background(), acp.SessionNotification{Update: acp.UpdateAgentMessageText("hello")})
if err != nil {
t.Fatal(err)
}
if sink.text != "hello" {
t.Fatalf("got %q, want hello", sink.text)
}
}
func TestHermesACPClientRejectsPermission(t *testing.T) {
t.Parallel()
client := newHermesACPClient()
response, err := client.RequestPermission(context.Background(), acp.RequestPermissionRequest{Options: []acp.PermissionOption{{
OptionId: "deny", Kind: acp.PermissionOptionKindRejectOnce, Name: "Reject",
}}})
if err != nil {
t.Fatal(err)
}
if response.Outcome.Selected == nil || response.Outcome.Selected.OptionId != "deny" {
t.Fatalf("unexpected response: %#v", response)
}
}
config.gopackage main
import (
"fmt"
"os"
"path/filepath"
"strings"
"gopkg.in/yaml.v3"
runtimeconfig "github.com/kagent-dev/kagent/go/adk/pkg/config"
configv1 "github.com/kagent-dev/kagent/go/api/gen/kagent/config/v1"
)
type hermesConfig struct {
Model struct {
Default string `yaml:"default"`
Provider string `yaml:"provider"`
BaseURL string `yaml:"base_url,omitempty"`
MaxTokens int `yaml:"max_tokens"`
} `yaml:"model"`
Providers map[string]hermesProvider `yaml:"providers"`
Agent struct {
SystemPrompt string `yaml:"system_prompt,omitempty"`
} `yaml:"agent"`
Terminal struct {
Cwd string `yaml:"cwd"`
} `yaml:"terminal"`
}
type hermesProvider struct {
BaseURL string `yaml:"base_url"`
KeyEnv string `yaml:"key_env"`
APIMode string `yaml:"api_mode"`
Model string `yaml:"model"`
}
// parseConfig reads the ADKConfig that kagent compiles for every BYO runtime.
func parseConfig(raw []byte) (*configv1.ADKConfig, error) {
cfg := new(configv1.ADKConfig)
if err := runtimeconfig.Unmarshal(raw, cfg); err != nil {
return nil, fmt.Errorf("decode %s: %w", configEnv, err)
}
return cfg, nil
}
func materializeHermesConfig(cfg *configv1.ADKConfig, dataDir, workspace string) error {
model := cfg.GetAgent().GetModel()
openai := model.GetOpenai()
if openai == nil {
return fmt.Errorf("Hermes BYO runtime currently supports only OpenAI ModelConfig")
}
if strings.TrimSpace(model.GetModel()) == "" {
return fmt.Errorf("OpenAI model name is required")
}
var output hermesConfig
output.Model.Default = model.GetModel()
output.Model.Provider = "openai"
output.Model.BaseURL = openai.GetBaseUrl()
output.Model.MaxTokens = int(openai.GetMaxCompletionTokens())
if output.Model.MaxTokens == 0 {
output.Model.MaxTokens = int(openai.GetMaxTokens())
}
if output.Model.MaxTokens == 0 {
output.Model.MaxTokens = 32768
}
if output.Model.BaseURL == "" {
output.Model.BaseURL = "https://api.openai.com/v1"
}
output.Providers = map[string]hermesProvider{"openai": {
BaseURL: output.Model.BaseURL,
KeyEnv: "OPENAI_API_KEY",
APIMode: "chat_completions",
Model: output.Model.Default,
}}
output.Agent.SystemPrompt = cfg.GetAgent().GetInstruction()
output.Terminal.Cwd = workspace
home := filepath.Join(dataDir, "hermes")
if err := os.MkdirAll(home, 0o700); err != nil {
return fmt.Errorf("create Hermes home: %w", err)
}
if err := os.MkdirAll(workspace, 0o700); err != nil {
return fmt.Errorf("create Hermes workspace: %w", err)
}
contents, err := yaml.Marshal(output)
if err != nil {
return fmt.Errorf("marshal Hermes configuration: %w", err)
}
if err := os.WriteFile(filepath.Join(home, "config.yaml"), contents, 0o600); err != nil {
return fmt.Errorf("write Hermes configuration: %w", err)
}
return nil
}
config_test.gopackage main
import (
"os"
"path/filepath"
"strings"
"testing"
)
func TestMaterializeHermesConfig(t *testing.T) {
t.Parallel()
root := t.TempDir()
workspace := filepath.Join(root, "workspace")
cfg, err := parseConfig([]byte(`{"runtime":{"control_plane_url":"http://kagent-controller.kagent:8083","name":"hermes-assistant","namespace":"kagent"},` +
`"agent":{"name":"hermes_assistant","instruction":"Be concise.","model":{"model":"gpt-4.1-mini","openai":{"base_url":"https://api.openai.com/v1"}}}}`))
if err != nil {
t.Fatal(err)
}
if err := materializeHermesConfig(cfg, root, workspace); err != nil {
t.Fatal(err)
}
contents, err := os.ReadFile(filepath.Join(root, "hermes", "config.yaml"))
if err != nil {
t.Fatal(err)
}
text := string(contents)
for _, expected := range []string{
"default: gpt-4.1-mini", "provider: openai", "base_url: https://api.openai.com/v1",
"max_tokens: 32768", "key_env: OPENAI_API_KEY", "api_mode: chat_completions", "system_prompt: Be concise.",
} {
if !strings.Contains(text, expected) {
t.Fatalf("configuration does not contain %q:\n%s", expected, text)
}
}
}
func TestMaterializeHermesConfigRejectsUnsupportedProvider(t *testing.T) {
t.Parallel()
cfg, err := parseConfig([]byte(`{"agent":{"name":"hermes_assistant","model":{"model":"claude-sonnet-4-5","anthropic":{}}}}`))
if err != nil {
t.Fatal(err)
}
err = materializeHermesConfig(cfg, t.TempDir(), t.TempDir())
if err == nil || !strings.Contains(err.Error(), "only OpenAI") {
t.Fatalf("expected unsupported provider error, got %v", err)
}
}
func TestParseConfigRejectsLegacyShape(t *testing.T) {
t.Parallel()
if _, err := parseConfig([]byte(`{"model":{"type":"openai","model":"gpt-4.1-mini"},"instruction":"Be concise."}`)); err == nil {
t.Fatal("expected the pre-1.0 configuration shape to be rejected")
}
}
main.gopackage main
import (
"cmp"
"context"
"encoding/json"
"flag"
"fmt"
"log/slog"
"os"
"strings"
a2atype "github.com/a2aproject/a2a-go/v2/a2a"
"github.com/kagent-dev/kagent/go/adk/pkg/app"
runtimea2a "github.com/kagent-dev/kagent/go/harness/runtime/a2a"
"github.com/kagent-dev/kagent/go/harness/runtime/continuation"
"github.com/kagent-dev/kagent/go/pkg/logging"
"github.com/kagent-dev/kagent/go/pkg/tracing"
)
const (
configEnv = "KAGENT_CONFIG_JSON"
agentCardEnv = "KAGENT_AGENT_CARD_JSON"
dataDir = "/data"
workspaceDir = "/data/workspace"
privatePort = "80"
)
func main() {
check := flag.Bool("check", false, "validate configuration and Hermes ACP startup, then exit")
flag.Parse()
logger, err := logging.New(os.Stderr, "info")
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
ctx := logging.IntoContext(context.Background(), logger)
if err := run(ctx, logger, *check); err != nil {
logger.ErrorContext(ctx, "Hermes Harness stopped", "error", err)
os.Exit(1)
}
}
func run(ctx context.Context, logger *slog.Logger, check bool) error {
configJSON, err := requiredEnvironment(configEnv)
if err != nil {
return err
}
agentCardJSON, err := requiredEnvironment(agentCardEnv)
if err != nil {
return err
}
var card a2atype.AgentCard
if err := json.Unmarshal(agentCardJSON, &card); err != nil {
return fmt.Errorf("decode Agent Card: %w", err)
}
if strings.TrimSpace(card.Name) == "" {
return fmt.Errorf("Agent Card name is required")
}
cfg, err := parseConfig(configJSON)
if err != nil {
return err
}
// The compiled runtime config carries the log level, so rebuild the logger once it is known.
if logger, err = logging.New(os.Stderr, cmp.Or(cfg.GetRuntime().GetLogLevel(), "info")); err != nil {
return err
}
ctx = logging.IntoContext(ctx, logger)
if err := materializeHermesConfig(cfg, dataDir, workspaceDir); err != nil {
return err
}
runner := newHermesRunner(logger, []string{"hermes", "acp"}, dataDir, workspaceDir)
defer runner.Close()
if check {
if err := runner.Check(ctx); err != nil {
return fmt.Errorf("check Hermes runtime: %w", err)
}
return nil
}
store, err := continuation.New(dataDir+"/adapter", "hermes", validateSessionID)
if err != nil {
return fmt.Errorf("create continuation store: %w", err)
}
// A BYO runtime has no compiled telemetry identity, so the executor gets the empty one.
executor, err := runtimea2a.New(runner, store, tracing.RuntimeTelemetry{})
if err != nil {
return fmt.Errorf("create A2A executor: %w", err)
}
application, err := app.New(app.AppConfig{
AgentCard: card,
Port: privatePort,
AppName: card.Name,
ControlPlaneURL: cfg.GetRuntime().GetControlPlaneUrl(),
Logger: logger,
}, executor)
if err != nil {
return fmt.Errorf("construct private A2A app: %w", err)
}
return application.Run()
}
func requiredEnvironment(name string) ([]byte, error) {
value := strings.TrimSpace(os.Getenv(name))
if value == "" {
return nil, fmt.Errorf("%s is required", name)
}
return []byte(value), nil
}
func validateSessionID(id string) error {
if strings.TrimSpace(id) == "" {
return fmt.Errorf("Hermes session ID is empty")
}
return nil
}
runner.gopackage main
import (
"context"
"errors"
"fmt"
"io"
"log/slog"
"os"
"os/exec"
"sync"
acp "github.com/coder/acp-go-sdk"
harnessruntime "github.com/kagent-dev/kagent/go/harness/runtime"
)
type hermesRunner struct {
logger *slog.Logger
command []string
dataDir string
workspace string
mu sync.Mutex
process *exec.Cmd
input io.WriteCloser
connection *acp.ClientSideConnection
client *hermesACPClient
sessionID string
}
func newHermesRunner(logger *slog.Logger, command []string, dataDir, workspace string) *hermesRunner {
return &hermesRunner{logger: logger, command: command, dataDir: dataDir, workspace: workspace}
}
func (r *hermesRunner) Check(ctx context.Context) error {
r.mu.Lock()
defer r.mu.Unlock()
return r.ensureConnected(ctx, "")
}
func (r *hermesRunner) Run(ctx context.Context, turn harnessruntime.Turn, sink harnessruntime.EventSink) (harnessruntime.Outcome, error) {
r.mu.Lock()
defer r.mu.Unlock()
if err := r.ensureConnected(ctx, turn.ContinuationID); err != nil {
return harnessruntime.Outcome{}, err
}
if turn.ContinuationID == "" {
if err := sink.SessionStarted(harnessruntime.SessionStarted{ContinuationID: r.sessionID}); err != nil {
return harnessruntime.Outcome{}, err
}
}
r.client.setSink(sink)
defer r.client.setSink(nil)
_, err := r.connection.Prompt(ctx, acp.PromptRequest{
SessionId: acp.SessionId(r.sessionID),
Prompt: []acp.ContentBlock{acp.TextBlock(turn.Prompt)},
})
if err != nil {
return harnessruntime.Outcome{}, fmt.Errorf("prompt Hermes session %s: %w", r.sessionID, err)
}
return harnessruntime.Outcome{}, nil
}
func (r *hermesRunner) ensureConnected(ctx context.Context, continuationID string) error {
if r.connection != nil {
select {
case <-r.connection.Done():
r.stopProcess()
default:
if continuationID == "" || continuationID == r.sessionID {
return nil
}
return fmt.Errorf("Hermes runtime is bound to session %s, not %s", r.sessionID, continuationID)
}
}
if len(r.command) == 0 {
return fmt.Errorf("Hermes command is required")
}
cmd := exec.Command(r.command[0], r.command[1:]...)
cmd.Dir = r.workspace
cmd.Env = append(os.Environ(), "HERMES_HOME="+r.dataDir+"/hermes", "HOME="+r.dataDir)
cmd.Stderr = os.Stderr
stdin, err := cmd.StdinPipe()
if err != nil {
return fmt.Errorf("open Hermes stdin: %w", err)
}
stdout, err := cmd.StdoutPipe()
if err != nil {
_ = stdin.Close()
return fmt.Errorf("open Hermes stdout: %w", err)
}
if err := cmd.Start(); err != nil {
_ = stdin.Close()
return fmt.Errorf("start Hermes ACP process: %w", err)
}
client := newHermesACPClient()
connection := acp.NewClientSideConnection(client, stdin, stdout)
connection.SetLogger(r.logger)
if _, err := connection.Initialize(ctx, acp.InitializeRequest{
ProtocolVersion: acp.ProtocolVersionNumber,
ClientCapabilities: acp.ClientCapabilities{},
}); err != nil {
stopCommand(cmd, stdin)
return fmt.Errorf("initialize Hermes ACP connection: %w", err)
}
if continuationID == "" {
session, err := connection.NewSession(ctx, acp.NewSessionRequest{Cwd: r.workspace, McpServers: []acp.McpServer{}})
if err != nil {
stopCommand(cmd, stdin)
return fmt.Errorf("create Hermes ACP session: %w", err)
}
r.sessionID = string(session.SessionId)
} else {
if _, err := connection.LoadSession(ctx, acp.LoadSessionRequest{
Cwd: r.workspace, SessionId: acp.SessionId(continuationID), McpServers: []acp.McpServer{},
}); err != nil {
stopCommand(cmd, stdin)
return fmt.Errorf("load Hermes ACP session %s: %w", continuationID, err)
}
r.sessionID = continuationID
}
r.process = cmd
r.input = stdin
r.connection = connection
r.client = client
return nil
}
func (r *hermesRunner) Close() error {
r.mu.Lock()
defer r.mu.Unlock()
return r.stopProcess()
}
func (r *hermesRunner) stopProcess() error {
var err error
if r.input != nil {
err = r.input.Close()
}
if r.process != nil && r.process.Process != nil {
if killErr := r.process.Process.Kill(); killErr != nil && !errors.Is(killErr, os.ErrProcessDone) && err == nil {
err = killErr
}
_ = r.process.Wait()
}
r.process = nil
r.input = nil
r.connection = nil
r.client = nil
r.sessionID = ""
return err
}
func stopCommand(cmd *exec.Cmd, input io.Closer) {
_ = input.Close()
if cmd.Process != nil {
_ = cmd.Process.Kill()
_ = cmd.Wait()
}
}