Agent Runtime Protocol

Swap the engine that runs an agent turn — built-in, custom, or plugin runtime.

from praisonaiagents import Agent

agent = Agent(name="runtime-agent", instructions="Execute tasks via the runtime protocol.")
agent.start("Process this request using the standard runtime protocol.")

One protocol, many runtimes — pick the engine that runs a single agent turn without changing your Agent code.

The user swaps runtimes without changing agent code; the registry resolves the engine and streams RuntimeResult deltas.

Quick Start

1. Run a turn with the built-in runtime

   import asyncio
   from praisonaiagents import resolve_runtime
   
   async def main():
       runtime = resolve_runtime("praisonai")
       result = await runtime.run_turn("Who built the Eiffel Tower?")
       print(result.content)
   
   asyncio.run(main())

2. Stream the response

   import asyncio
   from praisonaiagents import resolve_runtime
   
   async def main():
       runtime = resolve_runtime("praisonai")
       async for delta in runtime.stream_turn("Tell me a story"):
           if delta.type == "text":
               print(delta.content, end="")
   
   asyncio.run(main())

3. Register and use a custom runtime

   import asyncio
   from praisonaiagents import register_runtime, resolve_runtime
   from praisonaiagents.runtime import RuntimeResult, RuntimeDelta
   
   class EchoRuntime:
       def supports(self, model_ref=None):
           return True
   
       async def run_turn(self, prompt, **kwargs):
           return RuntimeResult(content=f"echo: {prompt}")
   
       async def stream_turn(self, prompt, **kwargs):
           yield RuntimeDelta(type="text", content=f"echo: {prompt}")
   
   register_runtime("echo", lambda: EchoRuntime())
   
   async def main():
       runtime = resolve_runtime("echo")
       result = await runtime.run_turn("Hello!")
       print(result.content)
   
   asyncio.run(main())

How It Works

The registry auto-discovers built-in and plugin runtimes, then hands back an instance implementing AgentRuntimeProtocol.

Picking a Runtime

Configuration Options

AgentRuntimeProtocol

Any object implementing these three methods is a valid runtime:

**kwargs understood by the built-in runtime: tools, max_tokens, temperature.

RuntimeConfig

RuntimeResult

RuntimeDelta

RuntimeRegistryEntry

RuntimeRegistry methods

Common Patterns

Implement a custom runtime

from praisonaiagents import register_runtime
from praisonaiagents.runtime import RuntimeResult, RuntimeDelta

class MyRuntime:
    def supports(self, model_ref=None):
        return True

    async def run_turn(self, prompt, *, system_prompt=None, model_ref=None, **kwargs):
        response = await my_llm_client.complete(prompt, system=system_prompt)
        if response.error:
            return RuntimeResult(content="", error=response.error)
        return RuntimeResult(content=response.text)

    async def stream_turn(self, prompt, **kwargs):
        async for token in my_llm_client.stream(prompt):
            yield RuntimeDelta(type="text", content=token)

register_runtime("my-llm", lambda: MyRuntime())

Plugin runtime via pyproject.toml

Ship your runtime as an installable package. The registry discovers it automatically at import time.

[project.entry-points."praisonai.runtimes"]
my-runtime = "my_package.runtime:MyRuntimeClass"

# my_package/runtime.py
from praisonaiagents.runtime import RuntimeResult, RuntimeDelta

class MyRuntimeClass:
    def supports(self, model_ref=None):
        return True

    async def run_turn(self, prompt, **kwargs):
        return RuntimeResult(content=f"handled: {prompt}")

    async def stream_turn(self, prompt, **kwargs):
        yield RuntimeDelta(type="text", content=f"handled: {prompt}")

Alias a runtime

from praisonaiagents.runtime.registry import add_runtime_alias

add_runtime_alias("default", "praisonai")

Replace the default runtime

from praisonaiagents.runtime.registry import unregister_runtime
from praisonaiagents import register_runtime

unregister_runtime("praisonai")
register_runtime("praisonai", lambda: MyCustomRuntime())

List available runtimes

from praisonaiagents import list_runtimes

for runtime_id in list_runtimes():
    print(runtime_id)

Check if a runtime is available

from praisonaiagents.runtime.registry import is_runtime_available

if is_runtime_available("my-runtime"):
    runtime = resolve_runtime("my-runtime")

Best Practices

Related