Asoba Ona Terminal
Home Insights Contact Us

Agent Integration

Powerful single-responsibility agents that integrate with external APIs for data processing and forecasting workflows.

Table of contents

  1. Overview
    1. Key Features
  2. 🔄 OODA Framework
  3. 📤 Upload Agent
    1. Purpose
    2. ✅ Real API Integration
    3. Commands
    4. Pipeline Monitoring
    5. Status Display
  4. 📈 Forecast Agent
    1. Purpose
    2. Current Status
    3. Commands
    4. Features
  5. 🔧 Agent Architecture
    1. Single-Responsibility Design
    2. Key Design Principles
  6. 🚀 Getting Started
    1. Prerequisites
    2. Setup
    3. Example Workflow
  7. 📊 Integration Test Results
    1. ✅ Working Components
    2. 🚧 Mocked Components
    3. Test Output Example
  8. 🔧 Configuration
    1. Environment Variables
    2. Local Storage
  9. 🛠️ Error Handling
    1. Upload Agent Errors
    2. CloudWatch Errors
    3. Forecast Agent Notices
  10. 💡 Next Steps
    1. For Upload Workflows
    2. For Forecast Workflows
    3. OODA Framework
  11. 📚 Additional Resources
  12. Get Help & Stay Updated

Overview

Ona Terminal includes a sophisticated agent system that bridges the gap between the terminal interface and external APIs. These agents are designed with single-responsibility principles and follow the OODA Loop framework for structured decision-making.

Key Features

🔄 OODA Framework

All agents operate within the OODA Loop framework for systematic decision-making:

  1. 🔍 Observe: Gather data from uploads, forecasts, and system status
  2. 🧭 Orient: Analyze patterns, risks, and opportunities
  3. 💡 Decide: Create actionable plans based on insights
  4. 🎯 Act: Execute approved plans with real-time monitoring

Each phase produces structured artifacts (insights-*.md, plan-*.md) for reproducibility and audit trails.

📤 Upload Agent

Purpose

Single-responsibility agent for uploading data files and monitoring the complete processing pipeline through to model training completion.

✅ Real API Integration

Commands

Upload Data

/upload-inverter upload CUSTOMER_ID LOCATION MANUFACTURER SERIAL_NUMBER FILE_PATH REGION CLIENT_ID

Example:

/upload-inverter upload SOLAR001 "Cape Town" "SolarEdge" SE12345 /data/inverter.csv af-south-1 client123

Check Status

# Check specific upload
/upload-inverter status UPLOAD_ID

# List all recent uploads  
/upload-inverter status

Pipeline Monitoring

Tracks the complete data processing pipeline:

  1. Upload → File uploaded to S3 via API Gateway
  2. Ingestion → ingestHistoricalLoadData Lambda processing
  3. Interpolation → dataInterpolation Lambda processing
  4. Training → trainForecaster Lambda and SageMaker training jobs

Status Display

Beautiful real-time status with emojis and progress indicators:

⚙️ Upload Status: PROCESSING
📋 Upload ID: SOLAR001_SE12345_1754151842
👤 Customer: SOLAR001
📍 Current Stage: trainForecaster
⏱️  Duration: 0:15:23

📜 Recent Logs:
   INFO: Data ingestion completed successfully
   INFO: Interpolation processing started
   INFO: Training job initiated

✅ Training completed! Use /forecast-inverter to generate predictions.

📈 Forecast Agent

Purpose

Single-responsibility agent for forecast generation and retrieval operations.

Current Status

Commands

Start Forecast Generation

/forecast-inverter start CUSTOMER_ID LOCATION MANUFACTURER SERIAL_NUMBER REGION FORECAST_TYPE HORIZON_DAYS FREQUENCY

Example:

/forecast-inverter start SOLAR001 "Cape Town" "SolarEdge" SE12345 af-south-1 P50 7 daily

Retrieve Forecast Results

/forecast-inverter get CUSTOMER_ID LOCATION MANUFACTURER SERIAL_NUMBER REGION OUTPUT_DIR FORECAST_TYPE

Example:

/forecast-inverter get SOLAR001 "Cape Town" "SolarEdge" SE12345 af-south-1 /tmp/forecasts P50

Check Status

# Check specific forecast
/forecast-inverter status REQUEST_ID

# List all recent forecasts
/forecast-inverter status

Features

🔧 Agent Architecture

Single-Responsibility Design

┌─────────────────────────────────────────────────────────────┐
│                    CLI Command Layer                        │
│        /upload-inverter    │    /forecast-inverter          │
├─────────────────────────────────────────────────────────────┤
│                   Agent Layer                               │
│  ┌─────────────────────┐  │  ┌─────────────────────────┐     │
│  │   Upload Agent      │  │  │  Forecast Agent         │     │
│  │ • File validation   │  │  │ • Generation (MOCK)     │     │
│  │ • API integration   │  │  │ • Retrieval (MOCK)      │     │
│  │ • Status monitoring │  │  │ • Status tracking       │     │
│  └─────────────────────┘  │  └─────────────────────────┘     │
├─────────────────────────────────────────────────────────────┤
│                  External Services                          │
│     Ona Power Tools API   │    CloudWatch Logs              │
│   S3 Upload Pipeline      │    Training Monitoring          │
└─────────────────────────────────────────────────────────────┘

Key Design Principles

🚀 Getting Started

Prerequisites

Setup

  1. Set API key: 
    export ONA_API_KEY="your_ona_api_key_here"
  2. Test upload agent (real API): 
    /upload-inverter upload TEST_CUSTOMER "Test Location" "TestMfg" TEST123 /path/to/data.csv af-south-1 test_client
  3. Test forecast agent (mock): 
    /forecast-inverter start TEST_CUSTOMER "Test Location" "TestMfg" TEST123 af-south-1 P50 7 daily

Example Workflow

  1. Upload data for training: 
    /upload-inverter upload SOLAR001 "Cape Town" "SolarEdge" SE12345 /data/solar_data.csv af-south-1 client123
  2. Monitor training progress: 
    /upload-inverter status SOLAR001_SE12345_1754151842
  3. Generate forecast when training complete: 
    /forecast-inverter start SOLAR001 "Cape Town" "SolarEdge" SE12345 af-south-1 P50 7 daily
  4. Retrieve forecast results: 
    /forecast-inverter get SOLAR001 "Cape Town" "SolarEdge" SE12345 af-south-1 /tmp/forecasts P50

📊 Integration Test Results

✅ Working Components

🚧 Mocked Components

Ready for real implementation when endpoints are available:

Test Output Example

✅ Upload Agent (REAL API): SUCCESS
   Upload ID: TEST_INTEGRATION_2303053195_1754151842
   S3 Key: historical/TEST_INTEGRATION/af-south-1/Cape Town/LuxPower/loadData.csv

✅ Forecast Agent (MOCK): SUCCESS
🚧 NOTE: Forecast APIs are mocked - real endpoints not yet implemented

✅ CLI Integration: SUCCESS
✅ OODA Framework: SUCCESS

🔧 Configuration

Environment Variables

Required

AWS Credentials

Local Storage

🛠️ Error Handling

Upload Agent Errors

❌ File not found: /path/to/file.csv
❌ File must be CSV format
❌ API error: 403 - Forbidden (check API key)
❌ API error: 413 - Payload too large

CloudWatch Errors

❌ Log group not found: /aws/lambda/ingestHistoricalLoadData
⚠️  Training status unknown - check AWS permissions

Forecast Agent Notices

🚧 MOCK: Simulating forecast generation API call...
🚧 MOCK: Simulating forecast results retrieval...
❌ Model training not complete. Current status: processing

💡 Next Steps

For Upload Workflows

For Forecast Workflows

OODA Framework

📚 Additional Resources

Ready to get started? Check out our Quick Start Guide or explore the full documentation.

Get Help & Stay Updated

Contact Support

For technical assistance, feature requests, or any other questions, please reach out to our dedicated support team.

Email Support Join Our Discord

Subscribe to Updates

* indicates required