Skip to main content

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., v3.8.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​

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

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

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")
}

Compatibility Matrix​

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

Platform VersionMinimum SDK VersionFeatures Added
v4.8.0v3.8.0Version discovery, capability registry
v4.7.0v3.7.0MCP standalone policy-check endpoints (check-input, check-output), circuit breaker pipeline wiring
v4.5.0v3.6.0WCP step-complete post-execution metrics (tokens, cost, output)
v4.4.0v3.5.0Media governance (multimodal image analysis), cost controls, budget enforcement
v4.3.0v3.4.0Multi-Agent Planning (MAP), Workflow Control Plane (WCP), execution replay, failWorkflow(), HITL queue API
v4.0.0v3.0.0Client 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 v4.7.0, use SDK v3.6.0 or v3.7.0.

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 get github.com/getaxonflow/axonflow-sdk-go/v3@latest
  1. Test in staging before rolling out to production.
  2. 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.

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.

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 v3.x requires platform v4.0.0 or later (for client credentials authentication). All v3.x SDKs work with any platform v4.x release.

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)
Last updated on