hydaelyn

README

Hydaelyn

Hydaelyn is a multi-agent parallel runtime for Go.

Embed it into your application with hydaelyn (or the lower-level host package) to run supervisor-controlled teams, deepsearch-style research flows, and other parallel agent workflows inside a normal Go program.

Install

go get github.com/Viking602/go-hydaelyn@latest

Quickstart

Run a multi-agent team without external API keys using a tiny local echo provider:

package main

import (
	"context"
	"fmt"

	"github.com/Viking602/go-hydaelyn"
	"github.com/Viking602/go-hydaelyn/pattern/deepsearch"
	"github.com/Viking602/go-hydaelyn/provider"
	"github.com/Viking602/go-hydaelyn/team"
)

type echoProvider struct{}

func (echoProvider) Metadata() provider.Metadata {
	return provider.Metadata{Name: "echo"}
}

func (echoProvider) Stream(_ context.Context, request provider.Request) (provider.Stream, error) {
	last := request.Messages[len(request.Messages)-1]
	return provider.NewSliceStream([]provider.Event{
		{Kind: provider.EventTextDelta, Text: last.Text},
		{Kind: provider.EventDone, StopReason: provider.StopReasonComplete},
	}), nil
}

func main() {
	runner := hydaelyn.New(hydaelyn.Config{})
	runner.RegisterProvider("echo", echoProvider{})
	runner.RegisterPattern(deepsearch.New())
	runner.RegisterProfile(team.Profile{Name: "supervisor", Role: team.RoleSupervisor, Provider: "echo", Model: "test"})
	runner.RegisterProfile(team.Profile{Name: "researcher", Role: team.RoleResearcher, Provider: "echo", Model: "test"})
	state, err := runner.StartTeam(context.Background(), hydaelyn.StartTeamRequest{
		Pattern:           "deepsearch",
		SupervisorProfile: "supervisor",
		WorkerProfiles:    []string{"researcher", "researcher"},
		Input: map[string]any{
			"query":      "compare options for a Go research assistant",
			"subqueries": []string{"runtime design", "tool integration"},
		},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(state.Result.Summary)
}

Core Concepts

Hydaelyn centers on the deepsearch pattern: parallel research tasks run simultaneously, optional verification checks their outputs, and a final synthesize task produces the result. The host runtime embeds into your application and coordinates supervisor and worker profiles. Supervisors orchestrate the workflow while workers execute tasks. All task outputs publish to a shared blackboard that downstream tasks read explicitly.

Examples + Read Next

Examples

• _examples/research - Local quickstart
• _examples/collab - Collaboration pattern
• _examples/tooling - Tool integration
• _examples/approval - Approval flows
• _examples/durable - Durable execution

Examples live under _examples/ (leading underscore) so they are skipped by go build ./.... Build or run one explicitly with go run ./_examples/research/.

Read Next

• Quickstart - Deep-dive tutorial
• Extensions - Stage / Capability / Output / Hook guide
• Task Dataflow - Dataflow documentation
• Recipe Compiler - Recipe/YAML configuration
• Evaluation - Performance evaluation
• Durable Execution - Replay and durability

Where Hydaelyn Fits

Hydaelyn is designed to live inside your Go application. You compose a host runtime, register providers, tools, patterns, and profiles, and then run supervisor-led teams in the same process as the rest of your system.

The CLI is useful for inspection and workflow support, but the library is the primary surface. MCP can be plugged in as one integration path, not as the core execution model. V1 stays single-process, and the intended extension model is composition around the runtime rather than subclassing a framework.

Development

See CONTRIBUTING.md for coding standards and contribution guidelines.

Documentation

Overview

Package hydaelyn is the root façade for the go-hydaelyn multi-agent runtime. It re-exports the most common entry points so simple programs can write:

runtime := hydaelyn.New(hydaelyn.Config{})

without importing any subpackage.

Subpackages host the real API surface, grouped by concern:

• host — runtime assembly, session store, plugin registry
• [agent] — agent engine and role definitions
• team — team orchestration, patterns, and run state
• [provider] — LLM provider drivers (anthropic, openai, scripted)
• [tool] — tool contract + kit/tooltest helpers
• [pattern] — reusable collaboration patterns
• [hook] — pre/post-turn hook contracts
• [transport] — MCP gateway and HTTP control plane
• [observe] — tracing and metrics observer interface
• [capability] — capability/security policy and context plumbing
• [mailbox] — agent-to-agent signal messaging (ask/answer/delegate)
• [planner] — planner contract and template provider
• [scheduler] — task queue and lease interfaces
• [storage] — run/workflow/session persistence drivers
• [message] — shared message/content data types
• [recipe] — YAML/JSON runtime configuration loader
• [eval] — evaluation suites and runners (eval/run, eval/cases)
• [cli] — command-line entry point implementation

Types under the internal/ tree are implementation details and are exposed only when they must appear in a public signature.

Index

• type Config
• type Profile
• type Role
• type Runtime
  • func New(cfg Config) *Runtime
• type StartTeamRequest

Types

type Config

type Config = host.Config

Public façade types. Each is a Go type alias for the equivalent type in a subpackage, so values constructed via either name are interchangeable.

type Profile

type Profile = team.Profile

Public façade types. Each is a Go type alias for the equivalent type in a subpackage, so values constructed via either name are interchangeable.

type Role

type Role = team.Role

Public façade types. Each is a Go type alias for the equivalent type in a subpackage, so values constructed via either name are interchangeable.

type Runtime

type Runtime = host.Runtime

Public façade types. Each is a Go type alias for the equivalent type in a subpackage, so values constructed via either name are interchangeable.

func New

func New(cfg Config) *Runtime

New constructs a Runtime from the given Config. It is a thin alias for host.New; callers that need to customise middleware, plugins, or session storage should import host directly.

type StartTeamRequest

type StartTeamRequest = host.StartTeamRequest

Public façade types. Each is a Go type alias for the equivalent type in a subpackage, so values constructed via either name are interchangeable.