Runtime Capabilities

Agents declare which capabilities they need, and the framework validates runtime support at construction time — failing fast instead of breaking mid-conversation.

Quick Start

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

With Configuration

Declare exactly which capabilities your agent requires.

from praisonaiagents import Agent, 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

Step	What happens
1	User passes `runtime=` parameter (any of 6 forms)
2	`resolve_runtime` normalises the value into a `RuntimeConfig`
3	If `validate_on_creation=True`, `validate_capabilities` checks the matrix
4	All capabilities present → Agent is ready
5	Any missing → `CapabilityValidationError` raised immediately

The `runtime=` Parameter

Six forms are accepted, all normalised to RuntimeConfig internally.

Form	Example	Resolves to
`None` (default)	`Agent(...)`	No runtime override — model-based resolution
`bool` True	`Agent(runtime=True)`	`RuntimeConfig()` with defaults
`bool` False	`Agent(runtime=False)`	`None` — runtime explicitly disabled
`str`	`Agent(runtime="native")`	`RuntimeConfig(preferred_runtime="native")`
`list` / `set` / `tuple` / `frozenset`	`Agent(runtime=["tool_loop", "mcp_tools"])`	`RuntimeConfig(required_capabilities=[...])`
`dict`	`Agent(runtime={"preferred_runtime": "native"})`	`RuntimeConfig(**value)`
`RuntimeConfig` instance	`Agent(runtime=RuntimeConfig(...))`	returned as-is

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

Configuration Options

`RuntimeConfig`

Option	Type	Default	Description
`required_capabilities`	`list / set / tuple / frozenset`	`None`	Capability names the runtime must support. Normalised to list automatically.
`preferred_runtime`	`str`	`None`	Preferred runtime ID: `"native"`, `"praisonai"`, `"claude-code"`, `"plugin-harness"`.
`fallback_allowed`	`bool`	`True`	Allow falling back to another runtime if the preferred one is unavailable.
`validate_on_creation`	`bool`	`True`	Validate capabilities at `Agent(...)` construction instead of first execution.
`metadata`	`dict`	`{}`	Free-form metadata passed through to the runtime.

`RuntimeCapability` Enum

12 capabilities are available:

Capability	Meaning
`NATIVE_HOOKS`	Pre-/post-/tool/error hooks fire in the runtime itself
`TOOL_LOOP`	Multi-turn tool-calling loop
`STREAMING_DELTAS`	Token-by-token streaming output
`CONTEXT_COMPACTION`	Automatic context window compaction
`MCP_TOOLS`	MCP (Model Context Protocol) tools
`CODE_EXECUTION`	Sandboxed code execution
`MULTI_MODAL`	Image / audio / file inputs
`ASYNC_EXECUTION`	Native `async`/`await` execution
`SESSION_PERSISTENCE`	Resumable sessions across restarts
`MEMORY_MANAGEMENT`	Native memory store integration
`BASIC_CHAT`	Plain prompt-and-response chat
`SIMPLE_TOOLS`	Single-shot tool calls (no loop)

Built-in Capability Matrices

Matrix	Capabilities	Use case
Native	All 12	Local `praisonai` / `native` runtime — full feature set
Reduced	`tool_loop`, `basic_chat`, `simple_tools` only	`claude-code`, `plugin-harness`, and unknown runtimes (safe default)

Runtime → Matrix Mapping

Runtime name	Matrix
`"native"`, `"praisonai"`	Native (full)
`"plugin"`, `"harness"`, `"reduced"`, `"plugin-harness"`, `"claude-code"`	Reduced
Anything else (unknown)	Reduced (safe default)

Common Patterns

Fail-fast on missing hooks

from praisonaiagents import Agent, 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, 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, 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

Always declare what you need

Use required_capabilities to document which features your agent depends on. This prevents silent feature degradation when switching runtimes — you’ll know immediately if the new runtime can’t support your agent.

Keep validate_on_creation=True

The default validate_on_creation=True catches mismatches at boot time, not mid-conversation. A fast, visible error at startup is always better than a cryptic failure during user interaction.

Use preferred_runtime='native' for full features

The native runtime supports all 12 capabilities. Only use "claude-code" or "plugin-harness" when you accept the reduced capability set (tool_loop, basic_chat, simple_tools).

For custom CLI backends, implement capabilities()

CliBackendProtocol now requires a capabilities() -> RuntimeCapabilityMatrix method. Without it, the backend reports as reduced capability only. Third-party backends must add this method to participate in capability validation.

CLI Backend Protocol

CLI backend integration (now deprecated in favour of runtime=)

YAML Configuration Reference

YAML agent options including the new runtime field

​Quick Start

​How It Works

​The runtime= Parameter

​Configuration Options

​RuntimeConfig

​RuntimeCapability Enum

​Built-in Capability Matrices

​Runtime → Matrix Mapping

​Common Patterns

​Fail-fast on missing hooks

​Allow fallback when preferred runtime unavailable

​Disable creation-time validation

​Catch validation errors

​Best Practices

​Related