Agent Technical Specifications

This document outlines the technical specifications for Stavily agents, covering their architecture, technology stack, plugin system, and operational requirements.

System Architecture

Core Components

The Stavily agent system consists of sensor and action agents that run on customer infrastructure, communicating with a central orchestrator for coordination.

Component	Technology	Purpose	Deployment
Sensor Agents	Go 1.21+	Event detection and monitoring	Docker/VM (Customer)
Action Agents	Go 1.21+	Task execution and system changes	Docker/VM (Customer)

Agent Architecture Diagram

graph TB
    subgraph "Customer Infrastructure"
        SA[Sensor Agent
Go Binary]
        AA[Action Agent
Go Binary]
        SPR[Sensor Plugin Repos]
        APR[Action Plugin Repos]
    end

    subgraph "Plugin Ecosystem"
        GH[GitHub]
        GL[GitLab]
        BB[Bitbucket]
    end

    SA -->|POST /triggers| OR[Orchestrator]
    AA -->|GET /actions| OR
    AA -->|POST /results| OR

    SA -.->|Git Clone/Pull| SPR
    AA -.->|Git Clone/Pull| APR

    SPR -.-> GH
    SPR -.-> GL
    APR -.-> BB

---

Technology Stack

Agent Stack

Go Agent Specifications

// Core Dependencies
go 1.21+
github.com/gorilla/mux v1.8.0
github.com/go-git/go-git/v5 v5.11.0
github.com/hashicorp/go-plugin v1.6.0
github.com/sirupsen/logrus v1.9.3

Agent Architecture

agent/
├── main.go                 # Entry point
├── core/
│   ├── agent.go           # Core agent logic
│   ├── api_client.go      # Orchestrator API client
│   ├── config.go          # Configuration management
│   └── plugin_manager.go  # Plugin lifecycle management
├── plugins/
│   ├── loader.go          # Plugin loading
│   ├── executor.go        # Plugin execution
│   └── sandbox.go         # Plugin isolation
├── sensor/                # Sensor agent specific
│   ├── monitor.go         # Monitoring logic
│   └── triggers.go        # Trigger detection
├── action/                # Action agent specific
│   ├── executor.go        # Action execution
│   └── polling.go         # Action polling
├── utils/
│   ├── git.go             # Git operations
│   ├── security.go        # Security utilities
│   └── logging.go         # Logging utilities

---

Plugin Architecture

Plugin Interface Specification

Trigger Plugin (Go)

type TriggerPlugin interface {
    Init(config map[string]interface{}) error
    Start(ctx context.Context) error
    Stop() error
    GetMetadata() PluginMetadata
    OnTrigger(callback func(TriggerEvent)) error
}

type TriggerEvent struct {
    ID          string                 `json:"id"`
    Timestamp   time.Time             `json:"timestamp"`
    Condition   map[string]interface{} `json:"condition"`
    Metadata    map[string]interface{} `json:"metadata"`
}

Action Plugin (Go)

type ActionPlugin interface {
    Init(config map[string]interface{}) error
    Execute(ctx context.Context, params map[string]interface{}) (*ActionResult, error)
    GetMetadata() PluginMetadata
    ValidateParams(params map[string]interface{}) error
}

type ActionResult struct {
    Status    string                 `json:"status"`
    Result    map[string]interface{} `json:"result"`
    Error     string                 `json:"error,omitempty"`
    Logs      []string              `json:"logs"`
    Timestamp time.Time             `json:"timestamp"`
}

Plugin Development SDK

Python Plugin SDK

from abc import ABC, abstractmethod
from typing import Dict, Any

class TriggerPlugin(ABC):
    @abstractmethod
    def init(self, config: Dict[str, Any]) -> None:
        pass

    @abstractmethod
    def start(self) -> None:
        pass

    @abstractmethod
    def stop(self) -> None:
        pass

    @abstractmethod
    def on_trigger(self, callback) -> None:
        pass

class ActionPlugin(ABC):
    @abstractmethod
    def init(self, config: Dict[str, Any]) -> None:
        pass

    @abstractmethod
    def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
        pass

    @abstractmethod
    def validate_params(self, params: Dict[str, Any]) -> bool:
        pass

---

Workflow Execution Flow

Workflow Lifecycle

sequenceDiagram
    participant SA as Sensor Agent
    participant OR as Orchestrator
    participant AA as Action Agent

    SA->>SA: Monitor via plugin
    SA->>OR: POST /triggers
    OR->>OR: Process trigger
    OR->>AA: Queue action
    AA->>AA: Execute plugin
    AA->>OR: POST /results

Workflow Definition Schema

workflow:
  id: string
  name: string
  description: string
  version: string

  triggers:
    - name: string
      plugin: string
      config: object
      conditions: object

  actions:
    - name: string
      plugin: string
      depends_on: [string]
      condition: string
      config: object
      timeout: duration
      retries: number

---

Monitoring & Observability

Agent Metrics

type AgentMetrics struct {
    AgentID           string    `json:"agent_id"`
    AgentType         string    `json:"agent_type"`
    Uptime           duration  `json:"uptime"`
    MemoryUsage      int64     `json:"memory_usage"`
    CPUUsage         float64   `json:"cpu_usage"`
    PluginCount      int       `json:"plugin_count"`
    ActivePlugins    int       `json:"active_plugins"`
    TriggerCount     int64     `json:"trigger_count"`
    ActionCount      int64     `json:"action_count"`
    SuccessRate      float64   `json:"success_rate"`
    LastHeartbeat    time.Time `json:"last_heartbeat"`
}

Logging Structure

{
  "timestamp": "2025-01-15T10:30:00Z",
  "level": "INFO",
  "component": "sensor-agent",
  "agent_id": "sensor-001",
  "event": "trigger_detected",
  "workflow_id": "cpu-remediation-001",
  "plugin": "prometheus-trigger-v1.0.0",
  "metadata": {
    "metric": "cpu_usage_percent",
    "value": 95.2,
    "threshold": 90.0
  },
  "trace_id": "abc123def456"
}

---

Deployment Specifications

Agent Deployment (Docker)

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download
RUN CGO_ENABLED=0 GOOS=linux go build -o sensor-agent cmd/sensor/main.go

FROM alpine:latest
RUN apk --no-cache add ca-certificates git
WORKDIR /root/
COPY --from=builder /app/sensor-agent .
COPY --from=builder /app/configs/sensor-agent.yaml .
CMD ["./sensor-agent", "--config", "sensor-agent.yaml"]

---

Performance Specifications

System Requirements

Agent Requirements

• CPU: 1+ core (1GHz+)
• Memory: 256MB+ RAM (Sensor), 512MB+ RAM (Action)
• Storage: 1GB+ available disk space
• Network: Stable internet connection

Performance Targets

Metric	Target	Measurement
Workflow Execution	<5s	Trigger to action start
Agent Heartbeat	30s	Configurable interval
Plugin Loading	<10s	Cold start time
Concurrent Workflows	1000+	Per orchestrator instance