🤖 Agent Registry & Coordination

#![allow(unused)]
fn main() {
pub struct AgentMetadata {
    pub id: String,                    // "architect", "developer-001"
    pub role: AgentRole,               // Architect, Developer, etc
    pub name: String,                  // "Senior Architect Agent"
    pub version: String,               // "0.1.0"
    pub status: AgentStatus,           // Active, Inactive, Updating, Error

    pub capabilities: Vec<Capability>, // [Design, ADR, Decisions]
    pub skills: Vec<String>,           // ["rust", "kubernetes", "distributed-systems"]
    pub llm_provider: LLMProvider,      // Claude, OpenAI, Gemini, Ollama
    pub llm_model: String,             // "opus-4"

    pub dependencies: Vec<String>,     // Agents this one depends on
    pub dependents: Vec<String>,       // Agents that depend on this one

    pub health_check: HealthCheckConfig,
    pub max_concurrent_tasks: u32,
    pub current_tasks: u32,
    pub queue_depth: u32,

    pub created_at: DateTime<Utc>,
    pub last_health_check: DateTime<Utc>,
    pub uptime_percentage: f64,
}

pub enum AgentRole {
    Architect, Developer, CodeReviewer, Tester,
    Documenter, Marketer, Presenter,
    DevOps, Monitor, Security,
    ProjectManager, DecisionMaker, Orchestrator,
}

pub enum AgentStatus {
    Active,
    Inactive,
    Updating,
    Error(String),
    Scaling,
}

pub struct Capability {
    pub id: String,        // "design-adr"
    pub name: String,      // "Architecture Decision Records"
    pub description: String,
    pub complexity: Complexity,  // Low, Medium, High, Critical
}

pub struct HealthCheckConfig {
    pub interval_secs: u32,
    pub timeout_secs: u32,
    pub consecutive_failures_threshold: u32,
    pub auto_restart_enabled: bool,
}
}

Agent Instance (Runtime)

#![allow(unused)]
fn main() {
pub struct AgentInstance {
    pub metadata: AgentMetadata,
    pub pod_id: String,              // K8s pod ID
    pub ip: String,
    pub port: u16,
    pub start_time: DateTime<Utc>,
    pub last_heartbeat: DateTime<Utc>,
    pub tasks_completed: u32,
    pub avg_task_duration_ms: u32,
    pub error_count: u32,
    pub tokens_used: u64,
    pub cost_incurred: f64,
}
}

📡 Inter-Agent Communication (NATS)

Message Protocol

#![allow(unused)]
fn main() {
pub enum AgentMessage {
    // Task assignment
    TaskAssigned {
        task_id: String,
        agent_id: String,
        context: TaskContext,
        deadline: DateTime<Utc>,
    },
    TaskStarted {
        task_id: String,
        agent_id: String,
        timestamp: DateTime<Utc>,
    },
    TaskProgress {
        task_id: String,
        agent_id: String,
        progress_percent: u32,
        current_step: String,
    },
    TaskCompleted {
        task_id: String,
        agent_id: String,
        result: TaskResult,
        tokens_used: u64,
        duration_ms: u32,
    },
    TaskFailed {
        task_id: String,
        agent_id: String,
        error: String,
        retry_count: u32,
    },

    // Communication
    RequestHelp {
        from_agent: String,
        to_roles: Vec<AgentRole>,
        context: String,
        deadline: DateTime<Utc>,
    },
    HelpOffered {
        from_agent: String,
        to_agent: String,
        capability: Capability,
    },
    ShareContext {
        from_agent: String,
        to_roles: Vec<AgentRole>,
        context_type: String,  // "decision", "analysis", "code"
        data: Value,
        ttl_minutes: u32,
    },

    // Coordination
    RequestDecision {
        from_agent: String,
        decision_type: String,
        context: String,
        options: Vec<String>,
    },
    DecisionMade {
        decision_id: String,
        decision: String,
        reasoning: String,
        made_by: String,
    },

    // Health
    Heartbeat {
        agent_id: String,
        status: AgentStatus,
        load: f64,  // 0.0-1.0
    },
}

// NATS Subjects (pub/sub pattern)
pub mod subjects {
    pub const TASK_ASSIGNED: &str = "vapora.tasks.assigned";        // Broadcast
    pub const TASK_PROGRESS: &str = "vapora.tasks.progress";        // Broadcast
    pub const TASK_COMPLETED: &str = "vapora.tasks.completed";      // Broadcast
    pub const AGENT_HELP: &str = "vapora.agent.help";              // Request/Reply
    pub const AGENT_DECISION: &str = "vapora.agent.decision";      // Request/Reply
    pub const AGENT_HEARTBEAT: &str = "vapora.agent.heartbeat";    // Broadcast
}
}

Pub/Sub Patterns

#![allow(unused)]
fn main() {
// 1. Broadcast: Task assigned to all interested agents
nats.publish("vapora.tasks.assigned", task_message).await?;

// 2. Request/Reply: Developer asks Help from Architect
let help_request = AgentMessage::RequestHelp { ... };
let response = nats.request("vapora.agent.help", help_request, Duration::from_secs(30)).await?;

// 3. Stream: Persist task completion for replay
nats.publish_to_stream("vapora_tasks", "vapora.tasks.completed", completion_message).await?;

// 4. Subscribe: Monitor listens all heartbeats
let mut subscription = nats.subscribe("vapora.agent.heartbeat").await?;
}

🏪 Agent Discovery & Installation

Marketplace API

#![allow(unused)]
fn main() {
pub struct AgentRegistry {
    pub agents: HashMap<String, AgentMetadata>,
    pub available_agents: HashMap<String, AgentManifest>,  // Registry
    pub running_agents: HashMap<String, AgentInstance>,    // Runtime
}

pub struct AgentManifest {
    pub id: String,
    pub name: String,
    pub version: String,
    pub role: AgentRole,
    pub docker_image: String,           // "vapora/agents:developer-0.1.0"
    pub resources: ResourceRequirements,
    pub dependencies: Vec<AgentDependency>,
    pub health_check_endpoint: String,
    pub capabilities: Vec<Capability>,
    pub documentation: String,
}

pub struct AgentDependency {
    pub agent_id: String,
    pub role: AgentRole,
    pub min_version: String,
    pub optional: bool,
}

impl AgentRegistry {
    // Discover available agents
    pub async fn list_available(&self) -> Vec<AgentManifest> {
        self.available_agents.values().cloned().collect()
    }

    // Install agent
    pub async fn install(
        &mut self,
        manifest: AgentManifest,
        count: u32,
    ) -> anyhow::Result<Vec<AgentInstance>> {
        // Check dependencies
        for dep in &manifest.dependencies {
            if !self.is_available(&dep.agent_id) && !dep.optional {
                return Err(anyhow::anyhow!("Dependency {} required", dep.agent_id));
            }
        }

        // Deploy to K8s (via Provisioning)
        let instances = self.deploy_to_k8s(&manifest, count).await?;

        // Register
        for instance in &instances {
            self.running_agents.insert(instance.metadata.id.clone(), instance.clone());
        }

        Ok(instances)
    }

    // Health monitoring
    pub async fn monitor_health(&mut self) -> anyhow::Result<()> {
        for (id, instance) in &mut self.running_agents {
            let health = self.check_agent_health(instance).await?;
            if !health.healthy {
                if health.consecutive_failures >= instance.metadata.health_check.consecutive_failures_threshold {
                    if instance.metadata.health_check.auto_restart_enabled {
                        self.restart_agent(id).await?;
                    }
                }
            }
        }
        Ok(())
    }
}
}

🔄 Shared State & Context

Context Management

#![allow(unused)]
fn main() {
pub struct SharedContext {
    pub project_id: String,
    pub active_tasks: HashMap<String, Task>,
    pub agent_states: HashMap<String, AgentState>,
    pub decisions: HashMap<String, Decision>,
    pub shared_knowledge: HashMap<String, Value>,  // RAG indexed
}

pub struct AgentState {
    pub agent_id: String,
    pub current_task: Option<String>,
    pub last_action: DateTime<Utc>,
    pub available_until: DateTime<Utc>,
    pub context_from_previous_tasks: Vec<String>,
}

// Access via MCP
impl SharedContext {
    pub async fn get_context(&self, agent_id: &str) -> anyhow::Result<AgentState> {
        self.agent_states.get(agent_id)
            .cloned()
            .ok_or(anyhow::anyhow!("Agent {} not found", agent_id))
    }

    pub async fn share_decision(&mut self, decision: Decision) -> anyhow::Result<()> {
        self.decisions.insert(decision.id.clone(), decision);
        // Notify interested agents via NATS
        Ok(())
    }

    pub async fn share_knowledge(&mut self, key: String, value: Value) -> anyhow::Result<()> {
        self.shared_knowledge.insert(key, value);
        // Index in RAG
        Ok(())
    }
}
}

🎯 Implementation Checklist

Define AgentMetadata + AgentInstance structs
NATS JetStream integration
Agent Registry CRUD operations
Health monitoring + auto-restart logic
Agent marketplace UI (Leptos)
Installation flow (manifest parsing, K8s deployment)
Pub/Sub message handlers
Request/Reply pattern implementation
Shared context via MCP
CLI: vapora agent list, vapora agent install, vapora agent scale
Logging + monitoring (Prometheus metrics)
Tests (mocking, integration)

✅ Agents register and appear in registry ✅ Health checks run every N seconds ✅ Unhealthy agents restart automatically ✅ NATS messages route correctly ✅ Shared context accessible to all agents ✅ Agent scaling works (1 → N replicas) ✅ Task assignment < 100ms latency

Version: 0.1.0 Status: ✅ Specification Complete (VAPORA v1.0) Purpose: Multi-agent registry and coordination system

VAPORA Platform Documentation

🤖 Agent Registry & Coordination

Multi-Agent Orchestration System

🎯 Objetivo

📋 Los 12 Roles de Agentes

Tier 1: Technical Core (Código)

Tier 2: Documentation & Communication

Tier 3: Operations & Infrastructure

Tier 4: Management & Coordination

🏗️ Agent Registry Structure

Agent Metadata (SurrealDB)