Flows

Flow methods enable component servers to evaluate workflow expressions and access runtime context during execution. These methods provide advanced integration capabilities for components that need to understand their execution environment.

Overview

The flow methods currently include:

1. flows/evaluate - Evaluate workflow expressions in runtime context
2. flows/get_metadata - Access flow and step metadata during execution

Additional flow methods may be added in future protocol versions for workflow introspection and runtime interaction.

Flow Method Sequences

Flow Evaluation Sequence

Metadata Access Sequence

flows/evaluate Method

Method Name: flows/evaluate Direction: Component Server → Runtime Type: Request (expects response)

Schema Viewer

Loading ....

Schema Source

{
  "description": "Sent from the component server to the Stepflow to evaluate a flow with the provided input.",
  "type": "object",
  "properties": {
    "flow_id": {
      "description": "The ID of the flow to evaluate (blob ID of the flow).",
      "$ref": "#/$defs/BlobId"
    },
    "input": {
      "description": "The input to provide to the flow.",
      "$ref": "#/$defs/Value"
    }
  },
  "required": [
    "flow_id",
    "input"
  ]
}

Schema Viewer

Loading ....

Schema Source

{
  "description": "Sent from the Stepflow back to the component server with the result of the flow evaluation.",
  "type": "object",
  "properties": {
    "result": {
      "description": "The result of the flow evaluation.",
      "$ref": "#/$defs/FlowResult"
    }
  },
  "required": [
    "result"
  ]
}

Request Example

{
  "jsonrpc": "2.0",
  "id": "eval-flow-001",
  "method": "flows/evaluate",
  "params": {
    "expression": {
      "$from": {"step": "data_processor"},
      "path": "$.results.total_count"
    }
  }
}

Response Example

{
  "jsonrpc": "2.0",
  "id": "eval-flow-001",
  "result": {
    "value": 42
  }
}

Expression Types

Workflow Input References

{
  "expression": {
    "$from": {"workflow": "input"},
    "path": "$.user.preferences.theme"
  }
}

Step Output References

{
  "expression": {
    "$from": {"step": "user_validation"},
    "path": "$.validation_result.is_valid"
  }
}

Complex Expressions

{
  "expression": {
    "user_data": {
      "$from": {"workflow": "input"},
      "path": "$.user"
    },
    "validation_status": {
      "$from": {"step": "user_validation"},
      "path": "$.status"
    },
    "static_config": {
      "timeout": 30
    }
  }
}

flows/get_metadata Method

Method Name: flows/get_metadata Direction: Component Server → Runtime Type: Request (expects response)

Schema Viewer

Loading ....

Schema Source

{
  "description": "Sent from the component server to Stepflow to get flow and step metadata.\n\nThis request allows components to access workflow-level metadata and step-specific metadata\nduring execution. The metadata can contain arbitrary JSON values defined in the workflow\nYAML/JSON.",
  "type": "object",
  "properties": {
    "flow_id": {
      "description": "The flow to retrieve metadata for.",
      "$ref": "#/$defs/BlobId"
    },
    "step_id": {
      "description": "The ID of the step to get metadata for (optional).\n\nIf not provided, only flow-level metadata is returned.\nIf provided, both flow metadata and the specified step's metadata are returned.\nIf the step_id doesn't exist, step_metadata will be None in the response.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "flow_id"
  ]
}

Schema Viewer

Loading ....

Schema Source

{
  "description": "Sent from Stepflow back to the component server with the requested metadata.\n\nContains the flow metadata and step metadata if a specific step was requested.\nThe metadata values are arbitrary JSON objects that can be accessed by components during\nworkflow execution.",
  "type": "object",
  "properties": {
    "flow_metadata": {
      "description": "Metadata for the current flow.\n\nThis always contains the flow-level metadata defined in the workflow file.\nCommon fields include name, description, version, but can contain any\narbitrary JSON structure defined by the workflow author.",
      "type": "object",
      "additionalProperties": true
    },
    "step_metadata": {
      "description": "Metadata for the specified step (only present if step_id was provided and found).\n\nThis contains step-specific metadata defined in the workflow file.\nWill be None if no step_id was provided in the request",
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "flow_metadata"
  ]
}

Request Example

{
  "jsonrpc": "2.0",
  "id": "get-metadata-001",
  "method": "flows/get_metadata",
  "params": {
    "step_id": "data_processor",
    "run_id": "123e4567-e89b-12d3-a456-426614174000",
    "flow_id": "sha256:abc123..."
  }
}

Response Example

{
  "jsonrpc": "2.0",
  "id": "get-metadata-001",
  "result": {
    "flow_metadata": {
      "name": "Data Processing Workflow",
      "description": "Processes user data through validation and transformation steps",
      "version": "1.0.0",
      "author": "Data Team",
      "timeout": 300,
      "retry_policy": {
        "max_attempts": 3,
        "backoff": "exponential"
      }
    },
    "step_metadata": {
      "timeout": 60,
      "critical": true,
      "description": "Validates and processes incoming data",
      "tags": ["validation", "processing"]
    }
  }
}