Runtime Configuration

Declare which runtime capabilities your agent requires and control runtime selection and validation

Tell the agent framework exactly which runtime features you need — it validates compatibility before your agent runs.

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    name="StreamingAgent",
    instructions="You stream responses to users.",
    runtime=RuntimeConfig(
        required_capabilities={"native_hooks", "streaming_deltas"},
        preferred_runtime="native",
    )
)

agent.start("Tell me about AI")

The user sets runtime requirements on the agent; compatibility is checked before the first turn runs.

Quick Start

1. Declare Required Capabilities

   Specify what your agent needs — the framework validates this before execution:

   from praisonaiagents import Agent
   from praisonaiagents.config import RuntimeConfig
   
   agent = Agent(
       name="HooksAgent",
       instructions="You use native hooks for monitoring.",
       runtime=RuntimeConfig(
           required_capabilities={"native_hooks", "tool_loop"},
       )
   )
   
   agent.start("Process this request")

2. Prefer a Specific Runtime with Fallback

   Request a specific runtime but allow fallback if unavailable:

   from praisonaiagents import Agent
   from praisonaiagents.config import RuntimeConfig
   
   agent = Agent(
       name="MCPAgent",
       instructions="You use MCP tools.",
       runtime=RuntimeConfig(
           preferred_runtime="native",
           required_capabilities={"mcp_tools"},
           fallback_allowed=True,       # Try other runtimes if "native" unavailable
           validate_on_creation=True,   # Fail fast at creation, not first run
       )
   )

Which Runtime Option Fits?

Pick the smallest option that expresses your requirement.

How It Works

Configuration Options

Precedence ladder:

# Level 1: Bool (default runtime, no requirements)
agent = Agent(runtime=True)

# Level 2: String (preferred runtime name)
agent = Agent(runtime="native")

# Level 3: List (required capabilities)
agent = Agent(runtime=["native_hooks", "streaming_deltas"])

# Level 4: RuntimeConfig (full control)
agent = Agent(runtime=RuntimeConfig(
    required_capabilities={"native_hooks"},
    preferred_runtime="native",
    fallback_allowed=True,
))

Common Patterns

Require streaming capability:

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    name="StreamBot",
    instructions="Stream responses character by character.",
    runtime=RuntimeConfig(
        required_capabilities={"streaming_deltas"},
        preferred_runtime="native",
    )
)

MCP-capable agent:

from praisonaiagents import Agent
from praisonaiagents.config import RuntimeConfig

agent = Agent(
    name="MCPAgent",
    instructions="Use MCP tools to complete tasks.",
    runtime=RuntimeConfig(
        required_capabilities={"mcp_tools", "tool_loop"},
        fallback_allowed=False,  # Fail if MCP isn't available
    )
)

Best Practices

Related