neqsim-agent-handoff

NeqSim Agent Handoff Schema

When agents need to pass results to other agents (e.g., @process.model output feeding @mechanical.design), use these structured formats to ensure no information is lost.

Handoff Principles

1. Explicit over implicit — include all parameters, don't assume the receiving agent can infer
2. Units always included — every numerical value has a unit
3. Code-ready — the receiving agent can directly use the values in NeqSim API calls
4. Traceable — include the source agent and any assumptions made

Schema 1: Fluid Definition Handoff

Pass from @thermo.fluid to any other agent:

{
  "handoff_type": "fluid_definition",
  "source_agent": "thermo.fluid",
  "eos_class": "SystemSrkEos",
  "mixing_rule": "classic",
  "temperature_K": 298.15,
  "pressure_bara": 60.0,
  "components": [
    {"name": "methane", "mole_fraction": 0.85},
    {"name": "ethane", "mole_fraction": 0.10},
    {"name": "propane", "mole_fraction": 0.05}
  ],
  "multi_phase_check": false,
  "characterization": null,
  "java_code": "SystemInterface fluid = new SystemSrkEos(298.15, 60.0);\nfluid.addComponent(\"methane\", 0.85);\nfluid.addComponent(\"ethane\", 0.10);\nfluid.addComponent(\"propane\", 0.05);\nfluid.setMixingRule(\"classic\");",
  "assumptions": ["Lean gas — no water, no C4+ components"]
}

Schema 2: Process Simulation Handoff

Pass from @process.model to @mechanical.design, @safety.depressuring, etc.:

{
  "handoff_type": "process_simulation",
  "source_agent": "process.model",
  "fluid_definition": { "...": "Schema 1 above" },
  "equipment": [
    {
      "name": "HP Separator",
      "type": "Separator",
      "inlet_temperature_C": 30.0,
      "inlet_pressure_bara": 60.0,
      "outlet_gas_temperature_C": 30.0,
      "outlet_gas_pressure_bara": 60.0,
      "outlet_liquid_temperature_C": 30.0,
      "outlet_liquid_pressure_bara": 60.0,
      "gas_flow_rate_kg_hr": 42000.0,
      "liquid_flow_rate_kg_hr": 8000.0,
      "gas_density_kg_m3": 45.2,
      "liquid_density_kg_m3": 520.0
    }
  ],
  "mass_balance_error_pct": 0.001,
  "energy_balance_error_pct": 0.01,
  "assumptions": ["Adiabatic separator", "No liquid carryover"]
}

Schema 3: Mechanical Design Handoff

Pass from @mechanical.design to @solve.task for reporting:

{
  "handoff_type": "mechanical_design",
  "source_agent": "mechanical.design",
  "equipment_name": "HP Separator",
  "design_pressure_barg": 72.0,
  "design_temperature_C": 100.0,
  "material_grade": "SA-516-70",
  "wall_thickness_mm": 28.5,
  "corrosion_allowance_mm": 3.0,
  "weight_empty_kg": 15200.0,
  "design_standard": "ASME VIII Div.1",
  "company_tr": "Equinor TR2000",
  "cost_estimate_usd": 450000.0,
  "assumptions": ["Joint efficiency 0.85", "No external loads"]
}

Schema 4: Flow Assurance Handoff

Pass from @flow.assurance to @solve.task or @process.model:

{
  "handoff_type": "flow_assurance",
  "source_agent": "flow.assurance",
  "hydrate_temperature_C": 18.5,
  "operating_temperature_C": 25.0,
  "subcooling_margin_C": 6.5,
  "hydrate_risk": "LOW",
  "wax_appearance_temperature_C": -5.0,
  "pipeline_pressure_drop_bar": 12.3,
  "arrival_temperature_C": 8.5,
  "assumptions": ["No MEG injection", "Seawater at 4 C"]
}

Schema 5: Safety Analysis Handoff

Pass from @safety.depressuring to reporting:

{
  "handoff_type": "safety_analysis",
  "source_agent": "safety.depressuring",
  "scenario": "Fire case blowdown",
  "initial_pressure_bara": 85.0,
  "final_pressure_bara": 6.9,
  "blowdown_time_minutes": 15.0,
  "minimum_temperature_C": -45.0,
  "mdmt_C": -46.0,
  "mdmt_margin_C": 1.0,
  "psv_required_area_cm2": 12.5,
  "assumptions": ["API 521 fire case", "Orifice Cd = 0.85"]
}

How to Use Handoff Schemas

Sending Agent (produces the handoff)

At the end of your work, format results into the appropriate schema:

# In a notebook or agent output
handoff = {
    "handoff_type": "process_simulation",
    "source_agent": "process.model",
    "equipment": [...],
    # ... fill all fields
}
# Include in the response to the orchestrating agent

Receiving Agent (consumes the handoff)

When you receive a handoff from another agent:

1. Validate the handoff — check all required fields are present
2. Use the values directly — temperatures, pressures, flows are ready to use
3. Preserve assumptions — carry forward assumptions from the source agent
4. Add your own assumptions — append to the assumptions list

Router Agent (orchestrates handoffs)

The @neqsim.help router agent manages handoffs when composing multi-agent pipelines:

1. Runs Agent A, captures handoff output
2. Passes handoff as context to Agent B
3. Agent B uses handoff values as inputs
4. Final results aggregated for user

Cross-Agent Consistency Checks

When receiving a handoff, verify consistency:

If a consistency check fails, alert the user before proceeding.

Schema 6: Lifecycle State Handoff

Use when passing a complete simulation state between agents — e.g., from a process simulation agent to a mechanical design agent, or between task iterations.

{
  "schema": "neqsim-lifecycle-state",
  "version": "1.0",
  "handoff": {
    "source_agent": "make a neqsim process simulation",
    "target_agent": "run neqsim mechanical design",
    "state_type": "ProcessSystemState | ProcessModelState",
    "state_name": "Gas Processing Base Case",
    "state_version": "1.0.0",
    "state_json": "<serialized JSON from ProcessSystemState.toJson()>",
    "compressed_bytes_base64": "<optional: base64-encoded compressed bytes for large states>",
    "validation": {
      "is_valid": true,
      "checksum": "abc123..."
    },
    "context": {
      "description": "HP/LP separation train for 50 MMSCFD wet gas",
      "key_results": {
        "gas_export_rate_MSm3_day": 1.2,
        "liquid_rate_m3_hr": 45.0
      }
    },
    "assumptions": [
      "SRK EOS with classic mixing rule",
      "Steady-state operation at plateau rate"
    ]
  }
}

Lifecycle State Fields

Creating a Lifecycle State Handoff

// Source agent creates the state
ProcessSystemState state = ProcessSystemState.fromProcessSystem(process);
state.setName("Gas Processing Base Case");
state.setVersion("1.0.0");
String stateJson = state.toJson();
boolean isValid = state.validate().isValid();

// For large states, use compressed bytes
byte[] compressed = state.toCompressedBytes();
String base64 = java.util.Base64.getEncoder().encodeToString(compressed);

Consuming a Lifecycle State Handoff

// Target agent loads the state
ProcessSystemState loaded = ProcessSystemState.fromJson(handoff.state_json);
ProcessSystemState.ValidationResult result = loaded.validate();
assert result.isValid();

// For multi-area states
ProcessModelState modelState = ProcessModelState.fromJson(handoff.state_json);

Version Comparison Across Handoffs

When multiple agents produce states at different design iterations, compare them:

ProcessModelState v1 = ProcessModelState.fromJson(handoff1.state_json);
ProcessModelState v2 = ProcessModelState.fromJson(handoff2.state_json);
ProcessModelState.ModelDiff diff = ProcessModelState.compare(v1, v2);
// diff.getModifiedParameters(), diff.getAddedEquipment(), diff.getRemovedEquipment()