Initialization

Initialization methods establish the protocol connection and negotiate capabilities between the Stepflow runtime and component servers.

Overview

Initialization Sequence

The initialization sequence establishes the protocol connection in two steps:

1. initialize - Runtime requests the initialize method and client responds.
2. initialized - Runtime sends initialized notification to indicate initialization is complete.

Both steps are required for proper protocol establishment.

initialize Method

The initialize method negotiates protocol version and establishes basic capabilities.

Method Name: initialize Direction: Runtime → Component Server Type: Request (expects response)

Request Schema

Schema Viewer

Loading ....

Schema Source

{
  "description": "Sent from Stepflow to the component server to begin the initialization process.",
  "type": "object",
  "properties": {
    "runtime_protocol_version": {
      "description": "Maximum version of the protocol being used by the Stepflow runtime.",
      "type": "integer",
      "format": "uint32",
      "minimum": 0
    },
    "observability": {
      "description": "Observability context for tracing initialization (trace context only, no flow/run).",
      "anyOf": [
        {
          "$ref": "#/$defs/ObservabilityContext"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "runtime_protocol_version"
  ]
}

Response Schema

Schema Viewer

Loading ....

Schema Source

{
  "description": "Sent from the component server back to Stepflow with the result of initialization.\nThe component server will not be initialized until it receives the `initialized` notification.",
  "type": "object",
  "properties": {
    "server_protocol_version": {
      "description": "Version of the protocol being used by the component server.",
      "type": "integer",
      "format": "uint32",
      "minimum": 0
    }
  },
  "required": [
    "server_protocol_version"
  ]
}

Request Example

{
  "jsonrpc": "2.0",
  "id": "b4d0c7e1-8f2a-4d3b-9c5a-1e7f8a9b2c3d",
  "method": "initialize",
  "params": {
    "runtime_protocol_version": 1
  }
}

Successful Response Example

{
  "jsonrpc": "2.0",
  "id": "b4d0c7e1-8f2a-4d3b-9c5a-1e7f8a9b2c3d",
  "result": {
    "server_protocol_version": 1
  }
}

Error Response Example

{
  "jsonrpc": "2.0",
  "id": "b4d0c7e1-8f2a-4d3b-9c5a-1e7f8a9b2c3d",
  "error": {
    "code": -32002,
    "message": "Server not initialized - protocol version mismatch",
    "data": {
      "runtime_version": 1,
      "server_version": 2,
      "supported_versions": [2],
      "message": "Server only supports protocol version 2, but runtime requested version 1"
    }
  }
}

initialized Notification

The initialized notification is sent by the runtime to confirm the server is ready for component requests.

Method Name: initialized Direction: Runtime → Component Server Type: Notification (no response expected)

Notification Format

{
  "jsonrpc": "2.0",
  "method": "initialized",
  "params": {}
}

Protocol Version Negotiation

Current version negotiation requires exact version matching:

Runtime Version	Server Version	Compatible	Result
1	1	✅ Yes	Proceed with protocol
1	2	❌ No	Connection terminated
2	1	❌ No	Connection terminated

Future protocol versions may support version ranges.