AgentOS Primer en

中文 | English

AgentOS Primer (for Power Engineers)

Maintained version: v0.51.2 ｜ Last updated: 2026-07-06

This page gives power industry engineers the foundational Agent / LLM / multi-agent AI concepts, so LlmClient, PPO, SHAP in EnerOS code are no longer jargon. Wiki-unique content.

---

1. Agent

Agent = Perception + Decision + Action in a closed loop.

Concept	Power system analogy
Agent	An automated operator (e.g., dispatcher Agent)
Perception	SCADA data acquisition
Decision	Dispatch strategy calculation
Action	Issue dispatch command

Agents in EnerOS are defined via the Agent trait (see eneros-agent); each Agent is an independent runtime unit with a lifecycle (spawn → run → stop).

EnerOS has 7 built-in domain Agents (see Agent Runtime):

• DispatchAgent (dispatch)
• SelfHealingAgent (fault self-healing)
• LoadForecastAgent (load forecasting)
• MaintenanceAgent (operations & maintenance)
• PlanningAgent (planning)
• TradingAgent (trading)
• EnergyAgent (energy efficiency)

---

2. LLM (Large Language Model)

LLM = a deep neural network trained on massive text, capable of generating natural language responses.

Term	Meaning
Prompt	Input text to the LLM ("Please suggest fault location")
Token	Minimal unit the LLM processes (≈ one Chinese character / half an English word)
Context Window	Max tokens the LLM can process at once (e.g., 8K, 32K, 128K)
Temperature	Randomness parameter, 0 = deterministic, 1 = high randomness
Hallucination	The LLM fabricates non-existent facts

EnerOS abstracts LLM calls via the LlmClient trait (see LLM Integration), supporting three backends:

• OpenAI (GPT-4o / o1)
• Anthropic (Claude 3.5 Sonnet)
• Ollama (local inference, recommended for edge deployment)

Key issue: LLMs are not safe — they may output commands exceeding authority (e.g., EmergencyOverride). EnerOS's LlmDecisionParser automatically rejects EmergencyOverride, converting to RequestApproval.

---

3. RAG (Retrieval-Augmented Generation)

LLMs have limited knowledge; RAG supplements domain knowledge via "retrieve then generate":

User question → Vectorize → Retrieve relevant docs → Concatenate Prompt → LLM generates answer

EnerOS provides in eneros-ai:

• EmbeddingModel trait — text vectorization (supports ONNX Runtime)
• VectorStore trait — vector storage and similarity retrieval (InMemoryVectorStore / UsearchStore)
• SemanticMemory — embedding retrieval + TF-IDF fallback

Power scenario application: During fault diagnosis, retrieve historical similar fault handling plans and inject into LLM context.

---

4. Multi-Agent Collaboration

Complex tasks are hard for a single Agent; multiple Agents collaborate:

Mode	English	Power analogy	EnerOS Implementation
Master-slave	MasterSlave	Dispatch center → substations	MasterSlaveCoordinator
Peer-to-peer	PeerToPeer	Inter-substation direct negotiation	PeerCoordinator
Contract net bidding	Bidding	Spot market bidding	BiddingCoordinator

CollaborationCoordinator trait uniformly abstracts the three modes; collaboration failure falls back to route_action.

See Agent Runtime and ADR-0010.

---

5. Reinforcement Learning (RL)

RL = Agent learns optimal policies through trial-and-error interaction with environment.

Term	Meaning
State	Current grid state (voltage, powerflow, load)
Action	Agent decision (e.g., adjust generator output)
Reward	Reward signal (e.g., +1 for violation reduction, +1 for cost reduction)
Policy	Policy π(a
Episode	A complete trial sequence

PPO (Proximal Policy Optimization) — current mainstream RL algorithm, used by OpenAI to train GPT. EnerOS's PpoAgent (in eneros-agent::learning) implements pure Rust MLP + optional candle GPU backend.

Safe constraint reward shaping — PowerRewardShaper converts grid safety constraints (voltage violations, thermal stability) into negative rewards, guiding PPO to learn safe policies.

---

6. Explainability

Power decisions must be explainable (regulatory requirement). EnerOS provides 4 explainers in eneros-agent::explain:

Explainer	Method	Use case
ShapExplainer	TreeSHAP / Integrated Gradients	Feature importance
LimeExplainer	LIME	Local linear approximation
AuditTrailExplainer	Audit reconstruction	Historical decision replay
CompositeExplainer	Priority composition	Multi-explainer fusion

Output formats: JSON / DOT (Graphviz) / Mermaid.

---

7. Agent Safety Boundaries

Power Agent decisions may affect the physical grid; safety boundaries are critical:

Risk	EnerOS Defense
LLM hallucination issues dangerous command	LlmDecisionParser rejects EmergencyOverride
Agent decision violates physical constraints	SafetyGateway type-level unbypassable
Decision latency exceeds budget	WCET framework 2× budget triggers watchdog
Audit tampered	HMAC-SHA256 chain hashing + WORM storage
Cross-tenant data leakage	Multi-tenant namespace isolation (404 not 403)

See Safety Gateway and Zero-Trust Security.

---

8. LLM Agent Real-Scenario Verification

v0.50.1+ introduces a standalone test crate tests/llm_verify/, running 100 real power scenarios with local Ollama to verify LLM Agent output matches scenarios:

Hard metric	Meaning	Threshold
C1	EmergencyOverride leakage	= 0
C2	JSON parse success rate	≥ 95%
C3	SafetyGateway bypass	= 0
C4	Audit completeness	= 100%

v0.50.2 adds a semantic correctness verification layer — 11 expectation rules + 3 matching dimensions (keyword / action_type / direction), 20-round main test entry.

See LLM Integration and ADR-0017 / ADR-0018.

---

Next Steps

• Power System Primer — Power systems crash course for SW/AI engineers
• Agent Runtime — 7 domain Agents + collaboration
• LLM Integration — LlmClient + real-scenario verification
• Safety Gateway — Agent decision safety boundaries
• Glossary — Terminology