Skip to main content
warp-md is built agent-first — every tool speaks JSON, emits structured progress, and returns deterministic results.

​
Why warp-md is Agent-Friendly

warp-md provides a contract-first API designed for AI agents and programmatic workflows:

Contract-First

Pydantic-validated schemas with deterministic outputs

Machine-Readable

JSON envelopes with structured error codes

CLI-Accessible

Any agent can invoke via subprocess

Streaming Support

NDJSON events for real-time progress

​
Agent Capabilities

CapabilityToolWhat Agents Can Do
Trajectory Analysiswarp-mdCalculate Rg, RMSD, RDF, conductivity (50+ analyses)
Molecular Packingwarp-packSolvate proteins, build simulation boxes
Peptide Buildingwarp-pepConstruct peptides, introduce mutations

​
JSON Envelope Outputs

All tools return structured JSON envelopes for reliable parsing:

​
Success Response

{
  "schema_version": "warp-md.agent.v1",
  "status": "ok",
  "exit_code": 0,
  "run_id": "run_20240315_143022",
  "output_dir": "./results",
  "analysis_count": 2,
  "started_at": "2024-03-15T14:30:22Z",
  "finished_at": "2024-03-15T14:30:45Z",
  "elapsed_ms": 23000,
  "warnings": [],
  "results": [
    {
      "analysis": "rg",
      "out": "rg.npz",
      "status": "ok",
      "artifact": {
        "path": "rg.npz",
        "format": "npz",
        "bytes": 4096,
        "sha256": "a1b2c3..."
      }
    },
    {
      "analysis": "rmsd",
      "out": "rmsd.npz",
      "status": "ok",
      "artifact": {
        "path": "rmsd.npz",
        "format": "npz",
        "bytes": 8192,
        "sha256": "d4e5f6..."
      }
    }
  ]
}

​
Error Response

{
  "schema_version": "warp-md.agent.v1",
  "status": "error",
  "exit_code": 3,
  "run_id": "run_20240315_143022",
  "analysis_count": 1,
  "started_at": "2024-03-15T14:30:22Z",
  "finished_at": "2024-03-15T14:30:23Z",
  "elapsed_ms": 1000,
  "warnings": [],
  "results": [],
  "error": {
    "code": "E_ANALYSIS_SPEC",
    "message": "rdf missing required fields: sel_a, sel_b",
    "context": {
      "analysis_index": 0,
      "analysis_name": "rdf"
    },
    "details": null,
    "traceback": null
  }
}
The exit_code field enables agents to distinguish error categories:
  • 0: Success
  • 2: Validation errors
  • 3: Analysis specification errors
  • 4: Runtime errors
  • 5: Internal errors

​
Structured Error Codes

All errors use machine-parseable codes for reliable recovery:
CodeExit CodeMeaningRecovery
E_CONFIG_VALIDATION2Schema validation failedFix request schema
E_CONFIG_VERSION2Unsupported schema versionUpdate schema version
E_CONFIG_MISSING_FIELD2Required field missingAdd missing field
E_ANALYSIS_UNKNOWN3Unknown analysis nameCheck analysis list
E_ANALYSIS_SPEC3Invalid analysis parametersAdd required parameters
E_SELECTION_EMPTY3Mask matched no atomsFix selection syntax
E_SELECTION_INVALID3Mask syntax errorCorrect selection mask
E_SYSTEM_LOAD4Failed to load topologyVerify file path/format
E_TRAJECTORY_LOAD4Failed to load trajectoryVerify file path/format
E_TRAJECTORY_EOF4Unexpected end of trajectoryCheck trajectory file
E_RUNTIME_EXEC4Analysis execution failedCheck input data
E_OUTPUT_WRITE4Failed to write outputCheck permissions
E_DEVICE_UNAVAILABLE4Requested device not availableUse different device
E_INTERNAL5Unexpected internal errorReport issue

​
Quick Start

# Single analysis
warp-md rg --topology protein.pdb --traj traj.xtc --selection "protein"
# Returns JSON envelope

# Batch analyses with streaming
warp-md run config.json --stream ndjson
# Emits NDJSON progress events

​
Agent Contract

All warp-md tools follow the same contract:
  1. Structured input - JSON schemas with Pydantic validation
  2. Structured output - JSON envelope with status, timing, and results
  3. Error codes - Machine-parseable error types with context
  4. Streaming - NDJSON events for long-running operations
  5. Artifacts - File paths with checksums and metadata
The agent contract is versioned (warp-md.agent.v1) to ensure backward compatibility as the API evolves.

​
Common Agent Patterns

​
Pattern 1: Batch Analysis

Run multiple analyses on the same trajectory in a single request: 
{
  "version": "warp-md.agent.v1",
  "system": "protein.pdb",
  "trajectory": "traj.xtc",
  "analyses": [
    {"name": "rg", "selection": "protein"},
    {"name": "rmsd", "selection": "backbone"},
    {"name": "rmsf", "selection": "protein"},
    {
      "name": "rdf",
      "sel_a": "resname SOL and name OW",
      "sel_b": "resname SOL and name OW",
      "bins": 200,
      "r_max": 10.0
    }
  ]
}

​
Pattern 2: Pipeline (Pack → Analyze)

Chain tools together for complete workflows: 
# 1. Pack the system
warp-pack --config pack.yaml --output packed.pdb --stream

# 2. Analyze the trajectory
warp-md run analysis.json --stream ndjson

​
Pattern 3: Iterative Design

Build, mutate, and analyze peptides: 
# 1. Build initial peptide
warp-pep build -s ACDEFG --output peptide.pdb --stream

# 2. Mutate and test
warp-pep mutate -i peptide.pdb -m A5G -o mutant.pdb --stream

# 3. Compare stability
warp-md rg --topology peptide.pdb --traj traj.xtc --selection protein
warp-md rg --topology mutant.pdb --traj traj.xtc --selection protein

​
Next Steps

Schema Reference

Explore Pydantic schemas and the complete agent contract

Framework Integrations

Integration patterns for LangChain, CrewAI, AutoGen, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us