Runtimes Service

The Runtimes Service provides programmatic access to manage agent runtime types and configurations in the Kubiya platform. Use this service to discover available runtimes, get runtime-specific requirements, and validate runtime configurations.

For conceptual information about runtimes and how they’re used in agents, see Runtimes Core Concepts.

Overview

The Runtimes Service enables you to:

List available runtimes including agno, claude_code, and custom runtimes
Get runtime requirements to understand specific runtime dependencies
Validate configurations before deploying agents

Quick Start

from kubiya import ControlPlaneClient

# Initialize client
client = ControlPlaneClient(api_key="your-api-key")

# List all available runtimes
runtimes = client.runtimes.list()
for runtime in runtimes:
    print(f"Runtime: {runtime['name']} - Type: {runtime['type']}")

# Get requirements for a specific runtime
requirements = client.runtimes.get_requirements("claude_code")
print(f"Required features: {requirements}")

List Runtimes

List all available agent runtime types.

Basic Listing

# List all runtimes
runtimes = client.runtimes.list()

for runtime in runtimes:
    print(f"""
    Name: {runtime['name']}
    Type: {runtime['type']}
    Description: {runtime.get('description', 'N/A')}
    Status: {runtime.get('status', 'active')}
    """)

Extract Runtime Information

def get_runtime_by_name(name: str):
    """Find a runtime by name"""
    runtimes = client.runtimes.list()

    for runtime in runtimes:
        if runtime['name'] == name:
            return runtime

    return None

# Usage
agno_runtime = get_runtime_by_name("agno")
if agno_runtime:
    print(f"Runtime: {agno_runtime['name']}")
    print(f"Description: {agno_runtime.get('description')}")

claude_code_runtime = get_runtime_by_name("claude_code")
if claude_code_runtime:
    print(f"Runtime: {claude_code_runtime['name']}")
    print(f"Features: {claude_code_runtime.get('features', [])}")

Filter Runtimes by Type

def filter_runtimes_by_type(runtime_type: str):
    """Filter runtimes by type"""
    runtimes = client.runtimes.list()

    return [r for r in runtimes if r.get('type') == runtime_type]

# Usage
builtin_runtimes = filter_runtimes_by_type("builtin")
print(f"Built-in runtimes: {len(builtin_runtimes)}")

custom_runtimes = filter_runtimes_by_type("custom")
print(f"Custom runtimes: {len(custom_runtimes)}")

Get Runtime Requirements

Get runtime-specific requirements for a runtime.

Basic Requirements Check

# Get requirements for claude_code runtime
requirements = client.runtimes.get_requirements("claude_code")

print(f"Runtime Requirements:")
print(f"  Model: {requirements.get('model_requirements', {})}")
print(f"  Features: {requirements.get('required_features', [])}")
print(f"  Environment: {requirements.get('environment', {})}")

Check Runtime Compatibility

def check_runtime_compatibility(runtime_id: str):
    """Check if a runtime has all required features"""
    try:
        requirements = client.runtimes.get_requirements(runtime_id)

        return {
            "runtime_id": runtime_id,
            "has_requirements": True,
            "required_features": requirements.get('required_features', []),
            "optional_features": requirements.get('optional_features', []),
            "model_requirements": requirements.get('model_requirements', {}),
        }
    except Exception as e:
        return {
            "runtime_id": runtime_id,
            "has_requirements": False,
            "error": str(e)
        }

# Usage
agno_compat = check_runtime_compatibility("agno")
print(f"Agno Runtime Compatibility: {agno_compat}")

claude_compat = check_runtime_compatibility("claude_code")
print(f"Claude Code Runtime Compatibility: {claude_compat}")

Compare Runtime Requirements

def compare_runtimes(runtime_ids: list):
    """Compare requirements across multiple runtimes"""
    comparison = {}

    for runtime_id in runtime_ids:
        try:
            requirements = client.runtimes.get_requirements(runtime_id)
            comparison[runtime_id] = {
                "required_features": requirements.get('required_features', []),
                "model_requirements": requirements.get('model_requirements', {}),
                "environment": requirements.get('environment', {})
            }
        except Exception as e:
            comparison[runtime_id] = {"error": str(e)}

    return comparison

# Usage
comparison = compare_runtimes(["agno", "claude_code", "standard"])

print("Runtime Comparison:")
for runtime_id, reqs in comparison.items():
    print(f"\n{runtime_id}:")
    if "error" in reqs:
        print(f"  Error: {reqs['error']}")
    else:
        print(f"  Features: {reqs.get('required_features', [])}")

Validate Runtime Configuration

Validate a runtime configuration before deployment.

Basic Validation

# Validate a runtime configuration
runtime_config = {
    "runtime_type": "agno",
    "model": "kubiya/claude-sonnet-4",
    "features": ["code_execution", "web_browsing"],
    "environment": {
        "timeout": 300,
        "max_retries": 3
    }
}

validation_result = client.runtimes.validate(runtime_config)

if validation_result.get('valid'):
    print("✅ Configuration is valid!")
else:
    print("❌ Configuration is invalid:")
    for error in validation_result.get('errors', []):
        print(f"  - {error}")

Validate with Error Handling

from kubiya.resources.exceptions import RuntimeError

def validate_runtime_config_safe(config: dict):
    """Validate runtime configuration with error handling"""
    try:
        result = client.runtimes.validate(config)

        if result.get('valid'):
            return {
                "success": True,
                "message": "Configuration is valid",
                "validated_config": result.get('validated_config', config)
            }
        else:
            return {
                "success": False,
                "message": "Configuration validation failed",
                "errors": result.get('errors', []),
                "warnings": result.get('warnings', [])
            }
    except RuntimeError as e:
        return {
            "success": False,
            "message": f"Validation error: {e}",
            "errors": [str(e)]
        }

# Usage
config = {
    "runtime_type": "claude_code",
    "model": "kubiya/claude-sonnet-4",
}

result = validate_runtime_config_safe(config)
print(f"Validation result: {result['message']}")
if not result['success']:
    print(f"Errors: {result['errors']}")

Pre-deployment Validation

def pre_deployment_check(agent_config: dict):
    """Comprehensive pre-deployment runtime validation"""
    runtime_type = agent_config.get('runtime_type')

    if not runtime_type:
        return {"valid": False, "error": "No runtime type specified"}

    # Get runtime requirements
    try:
        requirements = client.runtimes.get_requirements(runtime_type)
    except RuntimeError as e:
        return {"valid": False, "error": f"Invalid runtime: {e}"}

    # Validate configuration
    try:
        validation = client.runtimes.validate(agent_config)

        return {
            "valid": validation.get('valid', False),
            "runtime_type": runtime_type,
            "requirements_met": validation.get('requirements_met', False),
            "errors": validation.get('errors', []),
            "warnings": validation.get('warnings', [])
        }
    except RuntimeError as e:
        return {"valid": False, "error": str(e)}

# Usage
agent_config = {
    "runtime_type": "agno",
    "model": "kubiya/claude-sonnet-4",
    "skills": ["kubernetes", "terraform"],
    "environment": {"timeout": 600}
}

check_result = pre_deployment_check(agent_config)
if check_result['valid']:
    print("✅ Ready for deployment")
else:
    print(f"❌ Pre-deployment check failed: {check_result.get('error')}")
    print(f"Errors: {check_result.get('errors', [])}")

Practical Examples

1. Runtime Selection Helper

def select_best_runtime(requirements: dict):
    """Select the best runtime based on requirements"""
    runtimes = client.runtimes.list()

    required_features = requirements.get('features', [])
    model_preference = requirements.get('model_provider', '')

    suitable_runtimes = []

    for runtime in runtimes:
        runtime_id = runtime.get('name')

        try:
            runtime_reqs = client.runtimes.get_requirements(runtime_id)
            runtime_features = runtime_reqs.get('supported_features', [])

            # Check if runtime supports all required features
            if all(feature in runtime_features for feature in required_features):
                suitable_runtimes.append({
                    "runtime_id": runtime_id,
                    "runtime": runtime,
                    "requirements": runtime_reqs,
                    "match_score": len(set(required_features) & set(runtime_features))
                })
        except RuntimeError:
            continue

    # Sort by match score
    suitable_runtimes.sort(key=lambda x: x['match_score'], reverse=True)

    return suitable_runtimes[0] if suitable_runtimes else None

# Usage
requirements = {
    "features": ["code_execution", "file_system_access"],
    "model_provider": "Anthropic"
}

best_runtime = select_best_runtime(requirements)
if best_runtime:
    print(f"Recommended runtime: {best_runtime['runtime_id']}")
    print(f"Match score: {best_runtime['match_score']}")

2. Runtime Compatibility Matrix

def generate_compatibility_matrix():
    """Generate a compatibility matrix for all runtimes"""
    runtimes = client.runtimes.list()

    matrix = {}

    for runtime in runtimes:
        runtime_id = runtime.get('name')

        try:
            requirements = client.runtimes.get_requirements(runtime_id)

            matrix[runtime_id] = {
                "name": runtime.get('name'),
                "type": runtime.get('type'),
                "features": requirements.get('supported_features', []),
                "model_compatibility": requirements.get('model_requirements', {}),
                "status": runtime.get('status', 'active')
            }
        except RuntimeError:
            matrix[runtime_id] = {"error": "Failed to get requirements"}

    return matrix

# Usage
matrix = generate_compatibility_matrix()

print("Runtime Compatibility Matrix:")
print(f"{'Runtime':<20} {'Type':<15} {'Features':<30} {'Status':<10}")
print("-" * 75)

for runtime_id, info in matrix.items():
    if "error" in info:
        print(f"{runtime_id:<20} {'ERROR':<15} {info['error']:<30} {'N/A':<10}")
    else:
        features = ", ".join(info['features'][:2]) + "..." if len(info['features']) > 2 else ", ".join(info['features'])
        print(f"{info['name']:<20} {info['type']:<15} {features:<30} {info['status']:<10}")

3. Runtime Configuration Builder

class RuntimeConfigBuilder:
    """Helper class to build validated runtime configurations"""

    def __init__(self, client):
        self.client = client
        self.config = {}

    def set_runtime(self, runtime_type: str):
        """Set the runtime type"""
        self.config['runtime_type'] = runtime_type
        return self

    def set_model(self, model: str):
        """Set the model"""
        self.config['model'] = model
        return self

    def add_features(self, features: list):
        """Add features to the configuration"""
        self.config['features'] = features
        return self

    def set_environment(self, env_config: dict):
        """Set environment configuration"""
        self.config['environment'] = env_config
        return self

    def validate(self):
        """Validate the configuration"""
        return self.client.runtimes.validate(self.config)

    def build(self):
        """Build and return the configuration"""
        # Validate before building
        validation = self.validate()

        if not validation.get('valid'):
            raise ValueError(f"Invalid configuration: {validation.get('errors')}")

        return self.config

# Usage
builder = RuntimeConfigBuilder(client)

try:
    config = (builder
              .set_runtime("agno")
              .set_model("kubiya/claude-sonnet-4")
              .add_features(["code_execution", "web_browsing"])
              .set_environment({"timeout": 300, "max_retries": 3})
              .build())

    print(f"✅ Built valid configuration: {config}")
except ValueError as e:
    print(f"❌ Configuration error: {e}")

4. Runtime Health Monitor

def monitor_runtime_health():
    """Monitor health of all runtimes"""
    runtimes = client.runtimes.list()

    health_status = {
        "healthy": [],
        "unhealthy": [],
        "unknown": []
    }

    for runtime in runtimes:
        runtime_id = runtime.get('name')
        status = runtime.get('status', 'unknown')

        if status == 'active':
            health_status['healthy'].append(runtime_id)
        elif status == 'inactive' or status == 'error':
            health_status['unhealthy'].append(runtime_id)
        else:
            health_status['unknown'].append(runtime_id)

    return health_status

# Usage
health = monitor_runtime_health()
print(f"Runtime Health Status:")
print(f"  ✅ Healthy: {len(health['healthy'])} - {health['healthy']}")
print(f"  ❌ Unhealthy: {len(health['unhealthy'])} - {health['unhealthy']}")
print(f"  ⚠️  Unknown: {len(health['unknown'])} - {health['unknown']}")

Error Handling

from kubiya.resources.exceptions import RuntimeError

try:
    # Try to get runtime requirements
    requirements = client.runtimes.get_requirements("non-existent-runtime")
except RuntimeError as e:
    print(f"Runtime error: {e}")
    # Handle error - maybe fall back to default runtime
    print("Falling back to default runtime")
    runtimes = client.runtimes.list()
    default_runtime = runtimes[0] if runtimes else None
    if default_runtime:
        print(f"Using runtime: {default_runtime['name']}")

# Validate with error handling
try:
    config = {"runtime_type": "invalid"}
    validation = client.runtimes.validate(config)

    if not validation.get('valid'):
        print(f"Configuration invalid: {validation.get('errors')}")
except RuntimeError as e:
    print(f"Validation error: {e}")

Best Practices

1. Cache Runtime Information

# Cache runtimes to reduce API calls
class RuntimeCache:
    def __init__(self, client):
        self.client = client
        self._runtimes_cache = None
        self._requirements_cache = {}

    def get_runtimes(self):
        """Get cached runtimes"""
        if self._runtimes_cache is None:
            self._runtimes_cache = self.client.runtimes.list()
        return self._runtimes_cache

    def get_requirements(self, runtime_id: str):
        """Get cached requirements for a runtime"""
        if runtime_id not in self._requirements_cache:
            self._requirements_cache[runtime_id] = self.client.runtimes.get_requirements(runtime_id)
        return self._requirements_cache[runtime_id]

    def invalidate_cache(self):
        """Clear the cache"""
        self._runtimes_cache = None
        self._requirements_cache = {}

# Usage
cache = RuntimeCache(client)
runtimes = cache.get_runtimes()  # API call
runtimes_again = cache.get_runtimes()  # From cache

2. Always Validate Before Deployment

# Always validate runtime configuration before using
def deploy_agent_safe(agent_config: dict):
    """Deploy agent with pre-validation"""
    # Validate runtime configuration first
    validation = client.runtimes.validate(agent_config)

    if not validation.get('valid'):
        raise ValueError(f"Invalid runtime configuration: {validation.get('errors')}")

    # Proceed with deployment
    # ... deployment logic ...

    return {"success": True, "config": agent_config}

# Usage
config = {
    "runtime_type": "agno",
    "model": "kubiya/claude-sonnet-4"
}

try:
    result = deploy_agent_safe(config)
    print(f"✅ Agent deployed successfully")
except ValueError as e:
    print(f"❌ Deployment failed: {e}")

3. Check Requirements Before Configuration

def build_config_from_requirements(runtime_id: str):
    """Build configuration based on runtime requirements"""
    # Get requirements first
    requirements = client.runtimes.get_requirements(runtime_id)

    # Build config based on requirements
    config = {
        "runtime_type": runtime_id,
        "features": requirements.get('required_features', []),
        "environment": requirements.get('default_environment', {})
    }

    # Add model if specified in requirements
    if 'model_requirements' in requirements:
        model_reqs = requirements['model_requirements']
        if 'default_model' in model_reqs:
            config['model'] = model_reqs['default_model']

    return config

# Usage
config = build_config_from_requirements("agno")
print(f"Generated configuration: {config}")

4. Handle Runtime Unavailability

def get_runtime_with_fallback(preferred_runtime: str, fallback_runtime: str = "agno"):
    """Get runtime with automatic fallback"""
    try:
        # Try to get preferred runtime requirements
        requirements = client.runtimes.get_requirements(preferred_runtime)
        return {
            "runtime_id": preferred_runtime,
            "requirements": requirements,
            "is_fallback": False
        }
    except RuntimeError as e:
        print(f"Preferred runtime unavailable: {e}")
        print(f"Falling back to: {fallback_runtime}")

        try:
            requirements = client.runtimes.get_requirements(fallback_runtime)
            return {
                "runtime_id": fallback_runtime,
                "requirements": requirements,
                "is_fallback": True
            }
        except RuntimeError:
            raise ValueError("Both preferred and fallback runtimes unavailable")

# Usage
runtime = get_runtime_with_fallback("custom-runtime", "agno")
print(f"Using runtime: {runtime['runtime_id']}")
if runtime['is_fallback']:
    print("⚠️  Using fallback runtime")

API Reference

Methods

Method	Description	Parameters
`list()`	List all available runtimes	None
`get_requirements(runtime_id)`	Get runtime-specific requirements	`runtime_id`: Runtime identifier (e.g., ‘claude_code’)
`validate(runtime_config)`	Validate runtime configuration	`runtime_config`: Dictionary with runtime configuration

Runtime Object Structure

{
    "name": "string",                # Runtime name (e.g., "agno", "claude_code")
    "type": "string",                # Runtime type (e.g., "builtin", "custom")
    "description": "string",         # Runtime description
    "status": "string",              # Runtime status (e.g., "active", "inactive")
    "features": ["string"],          # Supported features
    "created_at": "string",          # Creation timestamp
    "updated_at": "string"           # Last update timestamp
}

Requirements Object Structure

{
    "required_features": ["string"],        # Required features
    "optional_features": ["string"],        # Optional features
    "supported_features": ["string"],       # All supported features
    "model_requirements": {                 # Model requirements
        "default_model": "string",
        "supported_providers": ["string"]
    },
    "environment": {                        # Environment configuration
        "timeout": int,
        "max_retries": int
    },
    "default_environment": dict            # Default environment settings
}

Validation Result Object Structure

{
    "valid": bool,                    # Whether configuration is valid
    "errors": ["string"],             # List of validation errors
    "warnings": ["string"],           # List of validation warnings
    "requirements_met": bool,         # Whether all requirements are met
    "validated_config": dict          # Validated configuration
}

Next Steps

Models Service

Manage LLM models

Skills Service

Configure tools and capabilities

Agents Service

Create and manage agents

Getting Started

Control Plane API

Control Plane Client

Context Graph & Memory

Client SDK

Workflow DSL

Advanced

Resources

​Overview

​Quick Start

​List Runtimes

​Basic Listing

​Extract Runtime Information

​Filter Runtimes by Type

​Get Runtime Requirements

​Basic Requirements Check

​Check Runtime Compatibility

​Compare Runtime Requirements

​Validate Runtime Configuration

​Basic Validation

​Validate with Error Handling

​Pre-deployment Validation

​Practical Examples

​1. Runtime Selection Helper

​2. Runtime Compatibility Matrix

​3. Runtime Configuration Builder

​4. Runtime Health Monitor

​Error Handling

​Best Practices

​1. Cache Runtime Information

​2. Always Validate Before Deployment

​3. Check Requirements Before Configuration

​4. Handle Runtime Unavailability

​API Reference

​Methods

​Runtime Object Structure

​Requirements Object Structure

​Validation Result Object Structure

​Next Steps

Models Service

Skills Service

Agents Service

Overview

Quick Start

List Runtimes

Basic Listing

Extract Runtime Information

Filter Runtimes by Type

Get Runtime Requirements

Basic Requirements Check

Check Runtime Compatibility

Compare Runtime Requirements

Validate Runtime Configuration

Basic Validation

Validate with Error Handling

Pre-deployment Validation

Practical Examples

1. Runtime Selection Helper

2. Runtime Compatibility Matrix

3. Runtime Configuration Builder

4. Runtime Health Monitor

Error Handling

Best Practices

1. Cache Runtime Information

2. Always Validate Before Deployment

3. Check Requirements Before Configuration

4. Handle Runtime Unavailability

API Reference

Methods

Runtime Object Structure

Requirements Object Structure

Validation Result Object Structure

Next Steps