localgreenchain/docs/AGENTS.md

LocalGreenChain Agent System

A comprehensive autonomous agent system for managing the LocalGreenChain ecosystem. The system consists of 10 specialized agents coordinated by a central orchestrator.

Overview

The agent system provides intelligent automation for:

• Plant lineage tracking and verification
• Transport and carbon footprint monitoring
• Consumer demand forecasting
• Vertical farm management
• Growing condition optimization
• Market matching between growers and consumers
• Sustainability monitoring
• Network analysis and discovery
• Data quality assurance
• Personalized grower advisory

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      AgentOrchestrator                          │
│  - Starts/stops agents          - Health monitoring             │
│  - Alert aggregation            - Event coordination            │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│ PlantLineage  │   │   Transport   │   │    Demand     │
│    Agent      │   │ TrackerAgent  │   │ ForecastAgent │
│ (60s cycle)   │   │ (120s cycle)  │   │ (300s cycle)  │
└───────────────┘   └───────────────┘   └───────────────┘
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│ VerticalFarm  │   │  Environment  │   │    Market     │
│    Agent      │   │ AnalysisAgent │   │ MatchingAgent │
│ (30s cycle)   │   │ (180s cycle)  │   │ (60s cycle)   │
└───────────────┘   └───────────────┘   └───────────────┘
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│Sustainability │   │   Network     │   │    Quality    │
│    Agent      │   │ DiscoveryAgent│   │AssuranceAgent │
│ (300s cycle)  │   │ (600s cycle)  │   │ (120s cycle)  │
└───────────────┘   └───────────────┘   └───────────────┘
                          │
                          ▼
                  ┌───────────────┐
                  │    Grower     │
                  │ AdvisoryAgent │
                  │ (300s cycle)  │
                  └───────────────┘

Quick Start

import { getOrchestrator, startAllAgents, stopAllAgents } from './lib/agents';

// Start all agents
await startAllAgents();

// Get orchestrator for management
const orchestrator = getOrchestrator();

// Check status
const status = orchestrator.getStatus();
console.log(`Running: ${status.runningAgents}/${status.totalAgents} agents`);

// Get dashboard data
const dashboard = orchestrator.getDashboard();

// Stop all agents
await stopAllAgents();

The 10 Agents

1. PlantLineageAgent

Purpose: Monitors and manages plant lineage tracking in the blockchain

Responsibilities:

• Validate new plant registrations
• Track generation lineage and ancestry
• Detect anomalies (orphans, circular references, invalid generations)
• Generate lineage reports and family trees
• Monitor plant status transitions

Key Methods:

const agent = getPlantLineageAgent();
agent.getLineageAnalysis(plantId);  // Get complete lineage for a plant
agent.getAnomalies();               // Get detected anomalies
agent.getNetworkStats();            // Get network-wide statistics

Cycle: 60 seconds | Priority: High

---

2. TransportTrackerAgent

Purpose: Monitors transport events and calculates environmental impact

Responsibilities:

• Track seed-to-seed transport lifecycle
• Calculate and aggregate carbon footprint
• Monitor food miles across the network
• Detect inefficient transport patterns
• Generate transport optimization recommendations

Key Methods:

const agent = getTransportTrackerAgent();
agent.getUserAnalysis(userId);       // Get user transport analysis
agent.getNetworkStats();             // Get network transport statistics
agent.getPatterns();                 // Get detected inefficiency patterns
agent.calculateSavingsVsConventional(); // Compare to conventional transport

Cycle: 120 seconds | Priority: High

---

3. DemandForecastAgent

Purpose: Autonomous demand forecasting and market intelligence

Responsibilities:

• Monitor consumer preference changes
• Generate regional demand signals
• Predict seasonal demand patterns
• Identify supply gaps and opportunities
• Provide early warnings for demand shifts

Key Methods:

const agent = getDemandForecastAgent();
agent.getRegionalSummaries();   // Get demand by region
agent.getOpportunities();       // Get market opportunities
agent.getTrends();              // Get demand trends
agent.getDemandAlerts();        // Get demand-related alerts

Cycle: 300 seconds | Priority: High

---

4. VerticalFarmAgent

Purpose: Autonomous vertical farm monitoring and optimization

Responsibilities:

• Monitor environmental conditions in all zones
• Detect anomalies and trigger alerts
• Optimize growing parameters
• Track crop batch progress
• Generate yield predictions
• Coordinate harvest scheduling

Key Methods:

const agent = getVerticalFarmAgent();
agent.getAllZones();            // Get all zone statuses
agent.getAllBatches();          // Get all batch progress
agent.getYieldPredictions();    // Get yield predictions
agent.getRecommendations();     // Get optimization recommendations
agent.getFarmSummary();         // Get overall farm summary

Cycle: 30 seconds | Priority: Critical

---

5. EnvironmentAnalysisAgent

Purpose: Analyzes growing conditions and provides optimization recommendations

Responsibilities:

• Compare growing environments across plants
• Identify optimal conditions for each species
• Generate environment improvement recommendations
• Track environmental impacts on plant health
• Learn from successful growing patterns

Key Methods:

const agent = getEnvironmentAnalysisAgent();
agent.getSpeciesProfile(species);      // Get optimal conditions for species
agent.getPlantScore(plantId);          // Get environment score for plant
agent.compareEnvironments(id1, id2);   // Compare two plant environments
agent.getSuccessPatterns();            // Get identified success patterns

Cycle: 180 seconds | Priority: Medium

---

6. MarketMatchingAgent

Purpose: Connects grower supply with consumer demand

Responsibilities:

• Match supply commitments with demand signals
• Optimize delivery routes and logistics
• Facilitate fair pricing
• Track match success rates
• Enable local food distribution

Key Methods:

const agent = getMarketMatchingAgent();
agent.registerSupplyOffer(offer);      // Register grower supply
agent.registerDemandRequest(request);  // Register consumer demand
agent.getAllMatches();                 // Get all market matches
agent.getPricingAnalysis();            // Get pricing data
agent.getMarketStats();                // Get market statistics

Cycle: 60 seconds | Priority: High

---

7. SustainabilityAgent

Purpose: Monitors and reports on environmental impact across the network

Responsibilities:

• Calculate network-wide carbon footprint
• Track food miles reduction vs conventional
• Monitor water usage in vertical farms
• Generate sustainability reports
• Identify improvement opportunities

Key Methods:

const agent = getSustainabilityAgent();
agent.getCarbonMetrics();          // Get carbon footprint metrics
agent.getFoodMilesMetrics();       // Get food miles metrics
agent.getWaterMetrics();           // Get water usage metrics
agent.getSustainabilityScore();    // Get overall sustainability score
agent.generateReport();            // Generate sustainability report

Cycle: 300 seconds | Priority: Medium

---

8. NetworkDiscoveryAgent

Purpose: Analyzes geographic distribution and connections in the plant network

Responsibilities:

• Map plant distribution across regions
• Identify network hotspots and clusters
• Suggest grower/consumer connections
• Track network growth patterns
• Detect coverage gaps

Key Methods:

const agent = getNetworkDiscoveryAgent();
agent.getClusters();               // Get identified network clusters
agent.getCoverageGaps();           // Get geographic coverage gaps
agent.getConnectionSuggestions();  // Get suggested connections
agent.getGrowthHistory();          // Get network growth history
agent.getNetworkAnalysis();        // Get full network analysis

Cycle: 600 seconds | Priority: Medium

---

9. QualityAssuranceAgent

Purpose: Verifies blockchain integrity and data quality

Responsibilities:

• Verify blockchain integrity
• Detect data anomalies and inconsistencies
• Monitor transaction validity
• Generate data quality reports
• Ensure compliance with data standards

Key Methods:

const agent = getQualityAssuranceAgent();
agent.triggerVerification();       // Manually trigger verification
agent.getIntegrityChecks();        // Get blockchain integrity results
agent.getQualityIssues();          // Get data quality issues
agent.getComplianceStatus();       // Get compliance status
agent.generateReport();            // Generate quality report

Cycle: 120 seconds | Priority: Critical

---

10. GrowerAdvisoryAgent

Purpose: Provides personalized recommendations to growers

Responsibilities:

• Generate planting recommendations based on demand
• Provide crop rotation advice
• Alert on optimal planting windows
• Analyze market opportunities
• Track grower performance metrics

Key Methods:

const agent = getGrowerAdvisoryAgent();
agent.getRecommendations(growerId);  // Get planting recommendations
agent.getRotationAdvice(growerId);   // Get crop rotation advice
agent.getOpportunities();            // Get market opportunities
agent.getPerformance(growerId);      // Get grower performance
agent.getSeasonalAlerts();           // Get seasonal alerts

Cycle: 300 seconds | Priority: High

---

Orchestrator API

Configuration

const orchestrator = getOrchestrator({
  autoStart: false,
  enabledAgents: ['plant-lineage-agent', 'transport-tracker-agent', ...],
  alertAggregationIntervalMs: 60000,
  healthCheckIntervalMs: 30000,
  maxAlertsPerAgent: 50
});

Management Methods

// Start/stop all agents
await orchestrator.startAll();
await orchestrator.stopAll();

// Manage individual agents
await orchestrator.startAgent('plant-lineage-agent');
await orchestrator.stopAgent('plant-lineage-agent');
await orchestrator.restartAgent('plant-lineage-agent');

Monitoring Methods

// Get orchestrator status
const status = orchestrator.getStatus();
// { isRunning, startedAt, uptime, totalAgents, runningAgents, healthyAgents, ... }

// Get agent health
const health = orchestrator.getAgentHealth('plant-lineage-agent');
// { agentId, status, tasksCompleted, errorRate, isHealthy, ... }

// Get all alerts
const alerts = orchestrator.getAlerts('critical');

// Get full dashboard
const dashboard = orchestrator.getDashboard();

Event Handling

orchestrator.on('orchestrator_started', (data) => {
  console.log(`Started with ${data.agentCount} agents`);
});

orchestrator.on('critical_alerts', (data) => {
  console.log(`${data.count} critical alerts!`);
});

Alert System

Each agent can generate alerts with the following severities:

• Critical: Immediate action required
• Warning: Attention needed soon
• Error: Something went wrong
• Info: Informational notification

Alerts are automatically aggregated by the orchestrator and can be retrieved:

const allAlerts = orchestrator.getAlerts();
const criticalAlerts = orchestrator.getAlerts('critical');

// Acknowledge an alert
orchestrator.acknowledgeAlert(alertId);

Health Monitoring

The orchestrator performs automatic health checks every 30 seconds:

• Monitors agent status and response times
• Calculates error rates
• Auto-restarts agents with >50% error rate
• Reports unhealthy agents

Best Practices

1. Start Order: Agents are started in priority order (critical → high → medium → low)
2. Error Handling: All agents have built-in retry logic and error recovery
3. Resource Management: Use singletons to avoid duplicate agent instances
4. Alert Management: Regularly acknowledge alerts to keep the system clean
5. Monitoring: Use the dashboard for real-time system visibility

Integration with Existing Systems

The agents integrate with existing LocalGreenChain systems:

• PlantChain: Plant lineage and registration
• TransportChain: Transport events and carbon tracking
• DemandForecaster: Consumer demand signals
• VerticalFarmController: Farm zone and batch management
• Environment Analysis: Growing condition comparison

Performance Considerations

• Memory: Each agent maintains its own cache; combined memory usage ~50-100MB
• CPU: Minimal CPU usage during idle periods; peak during analysis cycles
• Network: No external network calls unless configured (e.g., external APIs)
• Storage: Agents maintain in-memory state; orchestrator handles persistence

Future Enhancements

Planned improvements:

• Machine learning integration for demand prediction
• Automated agent scaling based on load
• Distributed agent deployment
• WebSocket real-time updates
• Mobile push notifications for alerts