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

Phase	What happens
1. Validate	Agent checks required capabilities against available runtimes
2. Select	Preferred runtime is used if available
3. Fallback	Alternative runtime used if preferred is unavailable and fallback_allowed=True
4. Execute	Agent runs on selected runtime

---

Configuration Options

Full list of options, types, and defaults — RuntimeConfig

Option	Type	Default	Description
required_capabilities	list[str] | None	None	Capabilities the agent requires
preferred_runtime	str | None	None	Preferred runtime implementation name
fallback_allowed	bool	True	Allow fallback if preferred runtime is unavailable
validate_on_creation	bool	True	Validate at agent creation (vs first execution)
metadata	dict | 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

Use validate_on_creation=True

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.

Allow fallback for resilience

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.

Check available capabilities

Capability names include streaming_deltas, tool_loop, mcp_tools, native_hooks. Use only documented capability names to ensure forward compatibility.

---

Related

Runtime Capabilities — full capabilities reference

Execution — control iteration limits and budget