Version Compatibility

AxonFlow SDKs and the AxonFlow platform are versioned independently but follow a coordinated release cadence. Each platform release may introduce new API endpoints that require a corresponding SDK update to access. Older SDK versions continue to work with newer platforms -- they simply cannot use the new features.

How Versioning Works

• Platform versions (e.g., v4.8.0) represent the server-side AxonFlow Agent and Orchestrator.
• SDK versions (e.g., v4.3.0) represent the client libraries (Go, Python, TypeScript, Java).
• SDKs are backward compatible -- an older SDK works against a newer platform for all features the SDK already supports.
• SDKs are not forward compatible -- a newer SDK calling endpoints that do not exist on an older platform will receive HTTP 404 errors for those specific methods.

Version Discovery

Starting with platform v4.8.0 and SDK v3.8.0, AxonFlow supports version discovery via the health endpoint. The health response includes a capabilities field that lists which features the running platform supports:

GET /health

{
  "status": "healthy",
  "version": "4.8.0",
  "capabilities": [
    {"name": "health_check", "since": "1.0.0", "description": "Basic health endpoint"},
    {"name": "proxy_llm_call", "since": "1.0.0", "description": "Proxy mode LLM calls with policy enforcement"},
    {"name": "audit_llm_call", "since": "1.0.0", "description": "Audit logging for LLM calls"},
    {"name": "static_policies", "since": "2.0.0", "description": "System policy CRUD"},
    {"name": "gateway_mode", "since": "3.0.0", "description": "Gateway mode integration"},
    {"name": "dynamic_policies", "since": "3.2.0", "description": "Runtime dynamic policy engine"},
    {"name": "multi_agent_planning", "since": "4.3.0", "description": "MAP plan and execute lifecycle"},
    {"name": "workflow_control", "since": "4.3.0", "description": "WCP workflow lifecycle management"},
    {"name": "execution_replay", "since": "4.3.0", "description": "Execution recording and replay"},
    {"name": "cost_controls", "since": "4.4.0", "description": "Budget and cost management"},
    {"name": "media_governance", "since": "4.4.0", "description": "Multimodal image governance"},
    {"name": "wcp_step_metrics", "since": "4.5.0", "description": "WCP step-complete post-execution metrics"},
    {"name": "mcp_check_endpoints", "since": "4.7.0", "description": "Standalone MCP policy check-input/check-output"},
    {"name": "circuit_breaker", "since": "4.7.0", "description": "Circuit breaker pipeline enforcement"},
    {"name": "version_discovery", "since": "4.8.0", "description": "Version and capability discovery"}
  ]
}

SDKs v3.8.0+ use this response to determine which methods are available at runtime, logging a warning if you call a method the platform does not advertise.

Checking Capabilities in Code

Go

import (
    "context"
    "fmt"
    "log"
    "os"

    axonflow "github.com/getaxonflow/axonflow-sdk-go/v5"
)

client := axonflow.NewClient(axonflow.AxonFlowConfig{
    Endpoint:     os.Getenv("AXONFLOW_ENDPOINT"),
    ClientID:     os.Getenv("AXONFLOW_CLIENT_ID"),
    ClientSecret: os.Getenv("AXONFLOW_CLIENT_SECRET"),
})

health, err := client.HealthCheckDetailed()
if err != nil {
    log.Fatalf("Health check failed: %v", err)
}

fmt.Printf("Platform version: %s\n", health.Version)

if health.HasCapability("mcp_check_endpoints") {
    // Safe to call MCPCheckInput / MCPCheckOutput
    result, err := client.MCPCheckInput(context.Background(), axonflow.MCPCheckInputRequest{
        ConnectorType: "postgres-prod",
        Statement:     userInput,
    })
    // ...
} else {
    fmt.Println("MCP policy check not available on this platform version")
}

Python

from axonflow import AxonFlow

async with AxonFlow(
    endpoint=os.environ["AXONFLOW_ENDPOINT"],
    client_id=os.environ["AXONFLOW_CLIENT_ID"],
    client_secret=os.environ["AXONFLOW_CLIENT_SECRET"],
) as client:
    health = await client.health_check_detailed()
    print(f"Platform version: {health.version}")

    if health.has_capability("mcp_check_endpoints"):
        result = await client.mcp_check_input(
            connector_type="postgres-prod",
            statement=user_input,
        )
        # ...
    else:
        print("MCP policy check not available on this platform version")

TypeScript

import { AxonFlow } from "@axonflow/sdk";

const client = new AxonFlow({
  endpoint: process.env.AXONFLOW_ENDPOINT,
  clientId: process.env.AXONFLOW_CLIENT_ID,
  clientSecret: process.env.AXONFLOW_CLIENT_SECRET,
});

const health = await client.healthCheck();
console.log(`Platform version: ${health.version}`);

if (AxonFlow.hasCapability(health, "mcp_check_endpoints")) {
  const result = await client.mcpCheckInput({
    connectorType: "postgres-prod",
    statement: userInput,
  });
  // ...
} else {
  console.log("MCP policy check not available on this platform version");
}

Java

import com.getaxonflow.sdk.AxonFlow;
import com.getaxonflow.sdk.AxonFlowConfig;

AxonFlowConfig config = AxonFlowConfig.builder()
    .endpoint(System.getenv("AXONFLOW_ENDPOINT"))
    .clientId(System.getenv("AXONFLOW_CLIENT_ID"))
    .clientSecret(System.getenv("AXONFLOW_CLIENT_SECRET"))
    .build();
AxonFlow client = AxonFlow.create(config);

HealthStatus health = client.healthCheck();
System.out.println("Platform version: " + health.getVersion());

if (health.hasCapability("mcp_check_endpoints")) {
    var result = client.mcpCheckInput("postgres-prod", userInput);
    // ...
} else {
    System.out.println("MCP policy check not available on this platform version");
}

Compatibility Matrix

The table below shows which SDK version is required for features introduced in each platform release.

Platform Version	Minimum SDK Version	Features Added
v7.0.1	Go v5.3.1 (recommended for auth fixes), Python v6.0.0, TS v5.0.0, Java v5.0.0	Patch release: unified auth across gateway/MCP/proxy, community-saas telemetry tracking, audit identity hardening. Go SDK v5.3.1 fixes missing auth headers on ListConnectors, GetConnector, GetConnectorHealth, GetPlanStatus, and all execution replay methods
v7.0.0	Go v5.0.0, Python v6.0.0, TS v5.0.0, Java v5.0.0	Governance profiles (AXONFLOW_PROFILE, AXONFLOW_ENFORCE), relaxed default detection actions, SDK telemetry endpoint_type field (SDKs v5.3.0 / v6.3.0), checkpoint retention bumped 90→180 days
v6.1.0	Go v5.0.0, Python v6.0.0, TS v5.0.0, Java v5.0.0	Mistral LLM provider, GovernedTool adapter (TS/Go/Java), checkToolInput/checkToolOutput aliases, Cursor/Codex integration
v6.0.0	Go v5.0.0, Python v6.0.0, TS v5.0.0, Java v5.0.0	X-Tenant-ID removed, auth required in eval/enterprise, proxied enterprise endpoints, PlanResponse status field
v4.8.0	v3.8.0	Version discovery, capability registry
v4.7.0	v3.7.0	MCP standalone policy-check endpoints (check-input, check-output), circuit breaker pipeline wiring
v4.5.0	v3.6.0	WCP step-complete post-execution metrics (tokens, cost, output)
v4.4.0	v3.5.0	Media governance (multimodal image analysis), cost controls, budget enforcement
v4.3.0	v3.4.0	Multi-Agent Planning (MAP), Workflow Control Plane (WCP), execution replay, failWorkflow(), HITL queue API
v4.0.0	v3.0.0	Client credentials authentication (OAuth2-style client_id + client_secret)

tip

All SDKs maintain backward compatibility within the v3.x line. Upgrading from v3.4.0 to v3.8.0 requires no code changes -- new methods are additive only.

Upgrade Recommendations

Keep SDKs Within One Minor Version of the Platform

For the best experience, keep your SDK version no more than one minor version behind the platform. For example, if your platform is v6.0.0, use the v5.0.0/v6.0.0 SDK releases.

Upgrade Path

1. Check your current platform version by calling the health endpoint: GET /health
2. Review the compatibility matrix above to see which features you are missing.
3. Update your SDK dependency:

Go

go get github.com/getaxonflow/axonflow-sdk-go/v5@latest

Python

pip install --upgrade axonflow

TypeScript

npm install @axonflow/sdk@latest

Java (Maven)

Update pom.xml:

<dependency>
    <groupId>com.getaxonflow</groupId>
    <artifactId>axonflow-sdk</artifactId>
    <version>5.3.0</version>
</dependency>

4. Test in staging before rolling out to production.
5. No code changes required -- new SDK versions are drop-in replacements.

Platform Upgrade Without SDK Upgrade

If you upgrade the platform but keep an older SDK:

• All existing SDK methods continue to work normally.
• New platform features are simply not accessible from the SDK.
• No errors are raised -- the SDK does not call endpoints it does not know about.

For many production teams, this is the safest rollout order: upgrade the platform first, verify health, policy behavior, and dashboards, then let application teams adopt newer SDK methods on their own schedule.

SDK Upgrade Without Platform Upgrade

If you upgrade the SDK but keep an older platform:

• All existing methods continue to work normally.
• Calling new SDK methods that map to endpoints not present on the older platform will return HTTP 404 errors.
• SDK v3.8.0+ logs a warning when the health endpoint reports missing capabilities, so you can catch this early.

This is where capability discovery becomes especially valuable. It lets one service start checking for newer MCP, orchestration, or governance features without assuming every environment is already on the latest platform release.

What Teams Usually Validate During Upgrades

Before rolling a new SDK or platform version across environments, the most useful checks are:

1. confirm the platform version and capability list from GET /health
2. verify auth mode, tenant headers, and deployment mode are unchanged
3. run one MCP flow and one orchestration flow in staging
4. confirm dashboards, audits, and policy decisions still look normal
5. only then enable newly introduced SDK methods or API surfaces

FAQ

What happens if I upgrade the SDK without upgrading the platform?

Existing features continue to work. New methods added in the SDK update will return HTTP 404 if the platform does not have the corresponding endpoints. Starting with SDK v3.8.0, the SDK checks the platform's capability list at initialization and logs a warning for any methods that may not be available.

What happens if I upgrade the platform without upgrading the SDK?

Nothing breaks. Your SDK continues to work with all the features it already supports. You simply will not have access to the new platform features until you also upgrade the SDK.

Can I run different SDK versions across services?

Yes. Each service can use its own SDK version independently. The platform handles requests from any supported SDK version. This is common during gradual rollouts where you upgrade one service at a time.

Is there a minimum platform version for any SDK version?

SDK v5.0.0 (Go/TS/Java) and v6.0.0 (Python) require platform v6.0.0 or later. Earlier SDK v3.x/v4.x versions work with platform v4.x/v5.x releases.

How do I check which platform version I am running?

Call the health endpoint directly:

curl https://your-axonflow-endpoint/health

Or use the SDK:

health = await client.health_check_detailed()
print(health.version)

Related Docs

• Choosing a Mode
• LLM Overview
• API Overview