Runtime Tool Result Middleware

Normalize tool results from plugin harnesses into a standard shape before hooks and memory see them

Runtime tool result middleware converts vendor-shaped tool outputs from plugin harnesses into a standard format before hooks and memory adapters run.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
agent.start("What is 2 + 2?")  # native praisonai runtime — no middleware needed

The user runs tools through a plugin harness; middleware normalises vendor-shaped results before hooks and memory run.

Quick Start

1. Simple Usage

   The native praisonai runtime needs no middleware — results pass straight to hooks:

   from praisonaiagents import Agent
   
   agent = Agent(name="assistant", instructions="Be helpful")
   agent.start("What is 2 + 2?")

2. With Configuration

   Register harness middleware once, then set agent._runtime_id:

   from typing import Any
   from praisonaiagents import Agent, tool
   from praisonaiagents.runtime import (
       MiddlewareContext,
       NormalizedToolResult,
       register_middleware,
   )
   
   
   class MyHarnessMiddleware:
       @property
       def runtime_id(self) -> str:
           return "my_plugin_harness"
   
       def normalize(self, result: Any, tool_name: str, ctx: MiddlewareContext) -> NormalizedToolResult:
           if isinstance(result, dict) and result.get("status") == "error":
               return NormalizedToolResult(
                   content=None,
                   success=False,
                   error_message=result.get("message"),
                   metadata={"vendor": "my_harness"},
                   raw_result=result,
               )
           return NormalizedToolResult(content=result.get("data", result), raw_result=result)
   
   
   register_middleware("my_plugin_harness", MyHarnessMiddleware())
   
   @tool
   def lookup(query: str) -> dict:
       """Look up data."""
       return {"status": "ok", "data": f"Results for {query}"}
   
   agent = Agent(name="assistant", tools=[lookup])
   agent._runtime_id = "my_plugin_harness"
   agent.start("Look up Python tutorials")

How It Works

Middleware runs in tool_execution.py before the AFTER_TOOL hook fires.

When agent._runtime_id is missing or equals "praisonai", middleware is bypassed entirely (zero allocation).

Configuration Options

MiddlewareContext

NormalizedToolResult

Registry API

Module helpers: register_middleware, get_middleware, get_default_middleware_registry().

Common Patterns

Error handling — set success=False and fill error_message; failed tools surface as "Tool Error: <message>" to the agent.

Rich metadata — attach vendor, version, cache hit, or region in metadata for observability hooks.

Conditional normalization — branch on tool_name prefix (e.g. search_ vs db_) inside normalize().

User Interaction Flow

Best Practices

Related