> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Turn Executor Protocol • AI Agent SDK

> TurnExecutorProtocol: Contract for *where* a session's agent turn executes (Issue #4011).

# TurnExecutorProtocol

> Defined in the [**protocols**](https://praison.ai/docs/sdk/reference/praisonaiagents/modules/protocols.md) module.

AI Agent

Contract for *where* a session's agent turn executes (Issue #4011).

The gateway calls :meth:`place` to obtain a :class:`TurnPlacement` for a
session, then :meth:`execute_turn` to run the turn on that placement, and
:meth:`teardown` to reclaim a placement's worker. The default
:class:`InProcessTurnExecutor` runs the turn on the current event loop,
reproducing today's behaviour exactly; an isolated executor (subprocess /
container / remote, in the wrapper) runs it on its own worker so a wedged,
runaway, or crashed turn is contained to its session.

Contract:

* :meth:`place` returns the placement that owns `session_id`'s
  turns. Implementations may cache a placement per session and bump
  its `epoch` when the backing worker is replaced.
* :meth:`execute_turn` runs `turn` (an `async` no-arg callable the
  gateway already built for this turn) on `placement` and returns
  its result. The in-process default awaits `turn` directly on the
  current loop. An isolated executor does **not** ship this live
  callable (and its captured loop/agent state) across a process
  boundary — the worker owns the session (via :meth:`place`) and
  rebuilds/dispatches the turn from serialisable inputs on its own
  side; `turn` then acts as the gateway-side await point for that
  worker's result. `cancel_token` carries the per-turn interrupt so
  the existing cancellation seam is preserved. `limits` optionally
  bounds the worker's CPU/memory/wall time (honoured by isolated
  executors; ignored in-process). It raises :class:`WorkerWedgedError`
  if the placement's worker can no longer make progress.
* :meth:`teardown` reclaims `placement`'s worker (kills the
  subprocess/container/remote worker, or is a no-op in-process),
  scoped to the owning session only.

A worker fault must fail *scoped*: tear down the offending placement and
re-place its session, never the whole gateway — mirroring the fail-safe,
blast-radius-contained defaults elsewhere.

## Methods

> [card] [place()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/TurnExecutorProtocol-place.md)
>
> Return the placement that owns `session_id`'s turns.

> [card] [execute\_turn()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/TurnExecutorProtocol-execute_turn.md)
>
> Run `turn` on `placement` and return its result.

> [card] [teardown()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/TurnExecutorProtocol-teardown.md)
>
> Reclaim `placement`'s worker (scoped to its session).

## Source

> [card] [View on GitHub](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/gateway/protocols.py#L7562)
>
> `praisonaiagents/gateway/protocols.py` at line 7562


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.