Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

docs(plan-execute): clarify Responses history requirement (#905)

ryan-lempka3bbea7a7c48d
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 900d30f5f..f8865b1ed 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -192,6 +192,10 @@ Use this path when you want routing inside your own Rust application rather than
behind a proxy. `switchyard-libsy` never calls a model itself: an algorithm
picks a target and hands the model call back to you.
+For plan/execute, supply conversation history, including tool calls and results,
+before routing. Responses API continuation IDs alone are not enough. See the
+[Responses API history requirement](routing_algorithms/plan_execute_routing.md#responses-api-history-requirement).
+
### Add the dependencies
```toml
diff --git a/docs/routing_algorithms/plan_execute_routing.md b/docs/routing_algorithms/plan_execute_routing.md
index b659429c4..6efab06b1 100644
--- a/docs/routing_algorithms/plan_execute_routing.md
+++ b/docs/routing_algorithms/plan_execute_routing.md
@@ -32,7 +32,26 @@ The first edit or write routes the full trajectory to the efficient target and
latches that choice by session ID. A failed edit still triggers the handoff.
Without a session ID, the first mutation must remain in the request history.
-Optional settings:
+## Responses API history requirement
+
+Plan/execute needs the conversation history to detect edits and hand the task to
+the executor. Continuing with only `previous_response_id` or a provider
+`conversation` ID and new input is not supported for this handoff.
+
+For example, a `function_call_output` contains the result and call ID, but not
+the tool name. Without the earlier `write_file` call, the router cannot tell that
+the result belongs to an edit and can stay on the planner.
+
+Send the conversation history in `input`, including earlier tool calls and their
+results. Omit `previous_response_id` and `conversation` so routing can switch
+models between turns.
+
+When embedding `libsy`, your application must supply that history in
+`Request.llm_request.messages` before routing. `libsy` does not fetch it from the
+provider. A stable session ID remembers a detected handoff, but cannot detect an
+edit missing from the request history.
+
+## Optional settings
| Key | Behavior |
|---|---|