Runtime Capabilities

Declare what your agent needs and validate runtime support before execution

Agents declare required capabilities and the framework validates runtime support at construction — failing fast instead of mid-conversation.

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    instructions="You are a research assistant",
    runtime=RuntimeConfig(
        preferred_runtime="native",
        required_capabilities=["tool_loop", "mcp_tools", "streaming_deltas"],
    ),
)
agent.start("Find the top 3 papers on RLHF this month")

The user declares required runtime capabilities on the agent; the framework validates support before execution starts.

Quick Start

1. Simple Usage

   Enable default capability validation with a single flag.

   from praisonaiagents import Agent
   
   agent = Agent(
       instructions="You are a research assistant",
       runtime=True,
   )
   
   agent.start("Find the top 3 papers on RLHF this month")

2. With Configuration

   Declare exactly which capabilities your agent requires.

   from praisonaiagents import Agent
   from praisonaiagents.config import RuntimeConfig
   
   agent = Agent(
       instructions="You are a research assistant",
       runtime=RuntimeConfig(
           preferred_runtime="native",
           required_capabilities=["tool_loop", "mcp_tools", "streaming_deltas"],
           fallback_allowed=True,
       ),
   )
   
   agent.start("Find the top 3 papers on RLHF this month")

How It Works

The runtime= Parameter

Six forms are accepted, all normalised to RuntimeConfig internally.

graph TB
    Q{What do I need?}
    Q -->|Just turn on validation| B["runtime=True"]
    Q -->|Turn off runtime| C["runtime=False"]
    Q -->|Pick a runtime by name| D["runtime=\"native\""]
    Q -->|List required capabilities| E["runtime=[\"tool_loop\", \"mcp_tools\"]"]
    Q -->|Dict config| F["runtime={\"preferred_runtime\": \"native\", ...}"]
    Q -->|Full control| G["runtime=RuntimeConfig(...)"]

    classDef question fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef option fill:#189AB4,stroke:#7C90A0,color:#fff

    class Q question
    class B,C,D,E,F,G option

Precedence ladder: Instance > Config > Dict > List > String > Bool > Default

Configuration Options

RuntimeConfig

RuntimeCapability Enum

12 capabilities are available:

Built-in Capability Matrices

Runtime → Matrix Mapping

Common Patterns

Fail-fast on missing hooks

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    instructions="You are an assistant with hooks",
    runtime=RuntimeConfig(
        preferred_runtime="native",
        required_capabilities=["native_hooks", "tool_loop"],
    ),
)

If the runtime doesn’t support native_hooks, the agent raises CapabilityValidationError immediately.

Allow fallback when preferred runtime unavailable

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    instructions="You are a research assistant",
    runtime=RuntimeConfig(
        preferred_runtime="native",
        required_capabilities=["streaming_deltas"],
        fallback_allowed=True,
    ),
)

Disable creation-time validation

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    instructions="You are a research assistant",
    runtime=RuntimeConfig(
        preferred_runtime="native",
        required_capabilities=["mcp_tools"],
        validate_on_creation=False,
    ),
)

Validation is deferred until the agent’s first execution.

Catch validation errors

from praisonaiagents import (
    RuntimeCapability,
    RuntimeCapabilityMatrix,
    CapabilityValidationError,
    validate_capabilities,
)

limited_runtime = RuntimeCapabilityMatrix(basic_chat=True, simple_tools=True)
required = {RuntimeCapability.NATIVE_HOOKS, RuntimeCapability.STREAMING_DELTAS}

try:
    validate_capabilities(limited_runtime, required, "plugin-harness")
except CapabilityValidationError as e:
    print(e.runtime_name)            # "plugin-harness"
    print(e.missing_capabilities)    # {NATIVE_HOOKS, STREAMING_DELTAS}
    print(e.available_capabilities)  # {BASIC_CHAT, SIMPLE_TOOLS}

The error message ends with: _”Remediation: select a runtime that supports the missing capabilities or remove unsupported entries from runtime.required_capabilities.”_

Best Practices

Related