Prepared Turn Context

One immutable plan per agent turn, shared by every runtime (native, plugin, CLI).

Build one frozen turn plan from an Agent and prompt — any runtime (native, plugin, CLI) executes the same context.

from praisonaiagents import Agent
from praisonaiagents.runtime import default_context_builder

agent = Agent(name="Researcher", instructions="Find facts and cite sources.")
context = default_context_builder.build_context(agent, "Who built the Eiffel Tower?")
print(context.to_dict())

The user sends a prompt; the runtime builds one shared PreparedTurnContext for the turn.

Quick Start

1. Simple Usage

   Inspect what the agent will send on the next turn:

   from praisonaiagents import Agent
   from praisonaiagents.runtime import default_context_builder
   
   agent = Agent(name="Writer", instructions="Summarise pull requests.")
   context = default_context_builder.build_context(agent, "Summarise this PR")
   
   print(context.has_tools(), context.get_message_count())
   print(context.to_dict())

2. With Configuration

   Run the same context through your own runtime by implementing TurnRuntimeProtocol:

   import asyncio
   from typing import List
   from praisonaiagents import Agent
   from praisonaiagents.runtime import (
       default_context_builder,
       PreparedTurnContext,
       RuntimeMode,
   )
   
   class MyHarness:
       async def run_turn(self, context: PreparedTurnContext) -> str:
           return f"Handled turn {context.correlation.turn_id} with {context.get_message_count()} messages."
   
       def supports_runtime_mode(self, mode: RuntimeMode) -> bool:
           return mode in (RuntimeMode.SYNC, RuntimeMode.ASYNC)
   
       def get_supported_modes(self) -> List[RuntimeMode]:
           return [RuntimeMode.SYNC, RuntimeMode.ASYNC]
   
   agent = Agent(name="Writer", instructions="Summarise pull requests.")
   context = default_context_builder.build_context(agent, "Summarise this PR")
   
   asyncio.run(MyHarness().run_turn(context))

How It Works

Key imports: PreparedTurnContext, default_context_builder, RuntimeMode, DeliveryChannels.

Tool Resolution

build_context(agent, prompt, tools=…) resolves tools from the kwarg first, then the agent:

from praisonaiagents import Agent
from praisonaiagents.runtime import default_context_builder

def lookup(topic: str) -> str:
    """Return a short fact about the topic."""
    return f"fact about {topic}"

agent = Agent(name="Researcher", instructions="Cite facts.", tools=[lookup])

# 1. Uses agent.tools
ctx1 = default_context_builder.build_context(agent, "Tell me about Paris")
assert ctx1.has_tools()

# 2. tools=None also uses agent.tools (same as omitting the kwarg)
ctx2 = default_context_builder.build_context(agent, "Tell me about Paris", tools=None)
assert ctx2.has_tools()

# 3. tools=[] explicitly disables tools for this turn
ctx3 = default_context_builder.build_context(agent, "Just chat", tools=[])
assert not ctx3.has_tools()

Configuration Options

STREAM and ASYNC_STREAM raise ValueError if delivery.has_streaming() is false.

Best Practices

Related