Energy Intelligence · Cluster 1

Agent tool contracts

Agents reach infrastructure only through these tools. No tool writes a setpoint. Every tool carries the nine requirements below; "specified" means the contract is fixed and the implementation does not exist yet.

Every tool must have

schemaauthenticationauthorizationdeterministic validationtimeoutprovenanceloggingfailure behaviourtest coverage

Tools

`inspect_grid_state()`

Snapshot of the twin at a timestamp: buses, branches, assets, measurements, active alarms.

Side effect: read · specified
Scope: tenant:read
Timeout: 2000 ms
Input: { tenant, network_id, at?: iso8601, depth?: 1|2|3 }
Output: { snapshot_id, state, provenance }
Validation: network_id belongs to tenant; at within retention
On failure: Return last consistent snapshot with stale=true; never partial state.
Module: kernel · twin

`retrieve_asset()`

Asset record, parameters, limits, connection point, health features.

Side effect: read · specified
Scope: tenant:read
Timeout: 1000 ms
Input: { tenant, asset_id }
Output: { asset, limits, provenance }
Validation: asset_id in tenant scope
On failure: 404 typed error; no fuzzy match.
Module: kernel

`run_power_flow()`

AC (Newton) or DC power flow on a snapshot with optional modifications.

Side effect: compute · specified
Scope: tenant:simulate
Timeout: 10000 ms
Input: { snapshot_id, method: ac|dc|pinn, modifications?: Action[] }
Output: { result_id, voltages, flows, converged, iterations, solver, latency_ms }
Validation: modifications typed and within asset limits
On failure: converged=false is a result, not an error; solver exception → typed error, no retry with another method silently.
Module: physics

`run_contingency()`

N-1 / N-k screening over a snapshot.

Side effect: compute · specified
Scope: tenant:simulate
Timeout: 30000 ms
Input: { snapshot_id, set: n-1|list, limit_margin_pct }
Output: { violations[], worst_case, latency_ms }
Validation: contingency list ⊂ network elements
On failure: Partial results carry completed=false and the list of unevaluated cases.
Module: physics

`run_forecast()`

Probabilistic forecast for load, PV, price or constraint at a node.

Side effect: compute · specified
Scope: tenant:read
Timeout: 5000 ms
Input: { tenant, target, horizon_h, quantiles[] }
Output: { forecast_id, series[quantile], model_version, backtest_error }
Validation: horizon ≤ model max; quantiles in (0,1)
On failure: Fallback to persistence baseline, flagged baseline=true.
Module: forecast

`simulate_action()`

Roll the twin forward under a candidate action set.

Side effect: simulate · specified
Scope: tenant:simulate
Timeout: 20000 ms
Input: { snapshot_id, actions: Action[], horizon_min }
Output: { sim_id, trajectory, constraint_report }
Validation: actions signed by proposer; within declared envelopes
On failure: Any constraint evaluation failure marks the sim invalid; invalid sims cannot be cited by request_authorization.
Module: twin · physics

`calculate_flexibility()`

Available up/down flexibility per asset and aggregate over a window.

Side effect: compute · specified
Scope: tenant:read
Timeout: 5000 ms
Input: { tenant, asset_ids[], window }
Output: { per_asset[], aggregate, assumptions[] }
Validation: window within forecast horizon
On failure: Assets with unknown limits are excluded and listed.
Module: optimize

`optimize_dispatch()`

MILP dispatch for BESS / DER portfolio against price, constraints and SoC.

Side effect: compute · specified
Scope: tenant:simulate
Timeout: 60000 ms
Input: { tenant, portfolio, objective, horizon_h, constraints }
Output: { plan_id, schedule, objective_value, baseline_value, gap, solver_status }
Validation: constraints reference known assets; objective from an enum
On failure: Infeasible → return the infeasibility certificate; time-limit → best bound with gap.
Module: optimize

`validate_constraints()`

Deterministic pass/fail of a plan against physics and policy, with margins.

Side effect: compute · specified
Scope: tenant:simulate
Timeout: 10000 ms
Input: { plan_id | sim_id }
Output: { pass, violations[], margins }
Validation: input exists and is not stale
On failure: Fail closed: any evaluation error is a fail.
Module: physics · policy

`request_authorization()`

Submit a validated plan for human or envelope authorization. The only tool that leaves the sandbox — and it produces a request, not a setpoint.

Side effect: request · specified
Scope: tenant:request
Timeout: 3000 ms
Input: { plan_id, sim_id, validation_id, explanation_id, requested_window }
Output: { request_id, status: pending|approved|denied, expires_at }
Validation: plan, sim and validation ids agree; validation.pass = true; explanation present
On failure: Denied by default on any inconsistency. Never retried automatically.
Module: NeuralBridge

`generate_explanation()`

Plain-language and structured explanation of a plan: assumptions, trade-offs, what was rejected.

Side effect: compute · specified
Scope: tenant:read
Timeout: 15000 ms
Input: { plan_id, audience: operator|manager|auditor, lang: en|de }
Output: { explanation_id, text, structured }
Validation: plan exists
On failure: No explanation → no authorization request possible.
Module: planning

`create_incident()`

Open an incident with evidence attached (snapshots, sims, forecasts).

Side effect: record · specified
Scope: tenant:write:incident
Timeout: 3000 ms
Input: { tenant, severity, title, evidence_ids[] }
Output: { incident_id }
Validation: evidence ids exist in tenant
On failure: Queued locally, retried, never dropped.
Module: kernel

`generate_audit_record()`

Append a hash-chained record of who asked what, what was computed, what was decided.

Side effect: record · specified
Scope: system
Timeout: 1000 ms
Input: { actor, tool, inputs_hash, outputs_hash, decision? }
Output: { record_id, chain_hash }
Validation: previous chain hash matches
On failure: Chain break halts all request tools until resolved.
Module: shared › audit

As of 2026-09-05Machine-readable: /api/energy/tools All resources: /api/energy/index

Written and maintained by Vincenzo Ceccarelli Grimaldi, Frankfurt am Main.