Agent Architecture

Agent Interface

Every agent implements the core Agent interface:

type Agent interface {
    // Name returns the agent's identifier
    Name() string
// Reconcile converges actual state to desired state
    Reconcile(ctx context.Context, desired, actual State) (*ExecutionPlan, error)
// Heal diagnoses and repairs an issue
    Heal(ctx context.Context, issue Issue) (*ExecutionPlan, error)
// Plan generates a plan without executing it
    Plan(ctx context.Context, desired, actual State) (*ExecutionPlan, error)
// Tools returns the agent's available tools
    Tools() []Tool
}

ExecutionPlan

An execution plan is a sequence of steps the agent intends to perform:

type ExecutionPlan struct {
    Steps      []Step
    RiskLevel  RiskLevel
    Reasoning  string
}
type Step struct {
    ToolName    string
    Parameters  map[string]interface{}
    Description string
    RiskLevel   RiskLevel
}

Tool System

Each tool has a name, description, typed parameters, risk level, and an execute function:

type Tool struct {
    Name        string
    Description string
    Parameters  []Parameter
    RiskLevel   RiskLevel
    Execute     func(ctx context.Context, params map[string]interface{}) (interface{}, error)
}
type Parameter struct {
    Name        string
    Type        string
    Description string
    Required    bool
}

Tools are registered with their agent at startup. The LLM selects which tools to use based on the task at hand. Each tool call is validated against its parameter schema before execution.

LLM Providers

The system supports multiple LLM providers:

## LLM Router

The LLM Router selects the appropriate model based on task complexity:

## Agent Runtime

The Agent Runtime is the host process for all agents:

1. Initialization: Loads all agents and registers their tools
2. Watch Loop: Subscribes to etcd key prefixes for state changes
3. Dispatch: Routes state changes to the responsible agent
4. Execution: Runs the agent's plan through the tool system
5. State Update: Writes results back to etcd

The runtime handles concurrency, rate limiting, retries, and graceful shutdown.