Runtime

Declare agent capability requirements and select the optimal runtime implementation

Runtime Config lets agents declare what capabilities they need — streaming, native hooks, MCP tools — and validates availability at startup.

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    name="Assistant",
    instructions="You are a real-time streaming assistant.",
    runtime=RuntimeConfig(
        required_capabilities={"streaming_deltas"},
        preferred_runtime="native",
    ),
)

agent.start("Explain the latest developments in fusion energy.")

The user enables runtime configuration on the agent; declared capabilities are validated at startup before the run proceeds.

Quick Start

1. Simple Usage

   from praisonaiagents import Agent
   from praisonaiagents.config import RuntimeConfig
   
   agent = Agent(
       instructions="You are a helpful assistant with streaming support.",
       runtime=RuntimeConfig(required_capabilities={"streaming_deltas"}),
   )
   agent.start("Write a short poem about autumn.")

2. With Preferred Runtime

   from praisonaiagents import Agent
   from praisonaiagents.config import RuntimeConfig
   
   agent = Agent(
       instructions="You are a tool-using assistant.",
       runtime=RuntimeConfig(
           preferred_runtime="native",
           required_capabilities={"tool_loop", "mcp_tools"},
           fallback_allowed=True,
       ),
   )
   agent.start("Search for and summarize recent Python release notes.")

How It Works

Configuration Options

Runtime Name Normalisation

preferred_runtime values are canonicalised before selection, so common spellings all resolve to the same capability matrix.

Normalisation is:

• Case-insensitive — NATIVE, Native, nAtIvE all resolve to native.
• Whitespace-tolerant — " native " is trimmed to native.
• Separator-agnostic — - and _ are interchangeable (plugin_harness = plugin-harness).

Alias Table

Source: RUNTIME_ALIASES in praisonaiagents.config.feature_configs.

Typo Detection

A value that is a close typo of a known runtime (e.g. nativ, natve, reducd, harnes) raises ValueError with a suggested spelling — instead of silently degrading to the reduced harness and dropping capabilities.

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

# Raises ValueError: "Unknown runtime 'nativ'. Did you mean 'native'?"
Agent(
    instructions="You are a helpful assistant.",
    runtime=RuntimeConfig(preferred_runtime="nativ"),
)

The typo check runs at agent construction, so a mistyped RuntimeConfig fails immediately rather than silently at runtime.

Plugin Runtimes Still Accepted

An unrecognised name that is not a close typo is treated as an opaque plugin runtime name and passed through unchanged — a third-party runtime registered later keeps working.

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

# Accepted as-is; falls back to the reduced harness
Agent(
    instructions="You are a helpful assistant.",
    runtime=RuntimeConfig(preferred_runtime="my-plugin-runtime"),
)

Normalised Input Surfaces

Every input form is normalised, and the caller’s object is never mutated — resolve_runtime returns a normalised copy.

from praisonaiagents import Agent

# String
Agent(instructions="…", runtime="NATIVE")

# Dict
Agent(instructions="…", runtime={"preferred_runtime": " native "})

# RuntimeConfig instance
from praisonaiagents.config import RuntimeConfig
Agent(instructions="…", runtime=RuntimeConfig(preferred_runtime="NATIVE"))

All three resolve preferred_runtime to native.

Common Patterns

Pattern 1 — Streaming-capable agent

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    instructions="You are a real-time assistant.",
    runtime=RuntimeConfig(
        required_capabilities={"streaming_deltas"},
        fallback_allowed=True,
    ),
)
response = agent.start("Write a detailed technical tutorial on async Python.")
print(response)

Pattern 2 — MCP-tools agent with strict requirements

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    instructions="You are an agent that uses MCP tools for file system operations.",
    runtime=RuntimeConfig(
        required_capabilities={"tool_loop", "mcp_tools", "native_hooks"},
        preferred_runtime="native",
        fallback_allowed=False,
    ),
)
agent.start("List all Python files modified in the last 7 days.")

Best Practices

Related