Skip to main content
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

PhaseWhat happens
1. ValidateAgent checks required capabilities against available runtimes
2. SelectPreferred runtime is used if available
3. FallbackAlternative runtime used if preferred is unavailable and fallback_allowed=True
4. ExecuteAgent runs on selected runtime

​
Configuration Options

Full list of options, types, and defaults — RuntimeConfig
OptionTypeDefaultDescription
required_capabilitieslist[str] | NoneNoneCapabilities the agent requires
preferred_runtimestr | NoneNonePreferred runtime implementation name
fallback_allowedboolTrueAllow fallback if preferred runtime is unavailable
validate_on_creationboolTrueValidate at agent creation (vs first execution)
metadatadict | None{}Additional runtime hints

​
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

Keeping validate_on_creation=True (the default) surfaces capability mismatches immediately when the agent is created, not halfway through a task. This prevents silent degradation.
Set fallback_allowed=True unless your agent strictly requires a specific runtime. Fallback lets the agent work even in environments where the preferred runtime isn’t installed.
Capability names include streaming_deltas, tool_loop, mcp_tools, native_hooks. Use only documented capability names to ensure forward compatibility.

Runtime Capabilities — full capabilities reference

Execution — control iteration limits and budget