From 4090e655e67b77965df90698648d5e6832ed8fc5 Mon Sep 17 00:00:00 2001 From: Ryan Lempka Date: Fri, 2 Oct 2026 12:42:22 -0500 Subject: [PATCH] docs(plan-execute): clarify Responses history requirement Signed-off-by: Ryan Lempka --- docs/getting_started.md | 4 ++++ .../plan_execute_routing.md | 21 ++++++++++++++++++- 2 files changed, 24 insertions(+), 1 deletion(-) 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 | |---|---|