From db1ce98cc4099d03b9daceda09d206b6cf5baba9 Mon Sep 17 00:00:00 2001 From: Maxwell Du <60411452+maxduu@users.noreply.github.com> Date: Sun, 8 Nov 2026 21:47:26 -0500 Subject: [PATCH 1/6] feat: conversational prompts with trim method --- .../uipath/src/uipath/agent/react/__init__.py | 4 + .../agent/react/conversational_prompts.py | 89 ++++++- .../react/test_conversational_prompts.py | 232 ++++++++++++++++++ 3 files changed, 320 insertions(+), 5 deletions(-) diff --git a/packages/uipath/src/uipath/agent/react/__init__.py b/packages/uipath/src/uipath/agent/react/__init__.py index 539f062b6..220c53885 100644 --- a/packages/uipath/src/uipath/agent/react/__init__.py +++ b/packages/uipath/src/uipath/agent/react/__init__.py @@ -6,7 +6,9 @@ from .conversational_prompts import ( PromptUserSettings, get_chat_system_prompt, + get_conversational_output_section, get_generate_output_prompt, + strip_conversational_output_section, ) from .conversational_voice_prompts import get_voice_system_prompt from .prompts import AGENT_SYSTEM_PROMPT_TEMPLATE @@ -31,6 +33,8 @@ "SetConversationalOutputToolSchemaModel", "PromptUserSettings", "get_chat_system_prompt", + "get_conversational_output_section", "get_generate_output_prompt", "get_voice_system_prompt", + "strip_conversational_output_section", ] diff --git a/packages/uipath/src/uipath/agent/react/conversational_prompts.py b/packages/uipath/src/uipath/agent/react/conversational_prompts.py index 18ace179f..94c815202 100644 --- a/packages/uipath/src/uipath/agent/react/conversational_prompts.py +++ b/packages/uipath/src/uipath/agent/react/conversational_prompts.py @@ -120,7 +120,9 @@ class PromptUserSettings(BaseModel): If execution cannot proceed: - State why -- Request missing or clarifying information""" +- Request missing or clarifying information + +{{CONVERSATIONAL_AGENT_SERVICE_PREFIX_outputSchemaPrompt}}""" _ATTACHMENTS_TEMPLATE = """===================================================================== ATTACHMENTS @@ -149,6 +151,7 @@ def get_chat_system_prompt( agent_name: str | None, user_settings: PromptUserSettings | None = None, conversation_id: str | None = None, + output_schema: type[BaseModel] | None = None, ) -> str: """Generate a system prompt for a conversational agent. @@ -158,6 +161,7 @@ def get_chat_system_prompt( agent_name: The agent display name; defaults to "Unnamed Agent" when None. user_settings: Optional user data that is injected into the system prompt. conversation_id: Optional conversation identifier that is injected into the system prompt. + output_schema: Optional structured output fields recorded after the conversational turn loop. Returns: The complete system prompt string @@ -193,6 +197,11 @@ def get_chat_system_prompt( get_conversation_id_template(conversation_id), ) + prompt = prompt.replace( + "{{CONVERSATIONAL_AGENT_SERVICE_PREFIX_outputSchemaPrompt}}", + get_conversational_output_section(output_schema), + ) + return prompt @@ -236,12 +245,82 @@ def get_conversation_id_template(conversation_id: str | None) -> str: return _CONVERSATION_ID_TEMPLATE.format(conversation_id=conversation_id) -_GENERATE_OUTPUT_INSTRUCTION = """The conversational response for this turn has already been delivered to the user. Call the `set_conversational_output` tool to record the structured output fields for this turn. +_OUTPUT_SECTION_PREFIX = """===================================================================== +STRUCTURED OUTPUT FOR THIS TURN +===================================================================== +At the end of your turn (when you decide to reply without calling a tool), +a separate step will infer structured output fields for this turn with the following schema: + +```json +""" + +_OUTPUT_SECTION_SUFFIX = """ +``` + +- The outputs are produced after your turn, by a separate step. You have no tool for them: + do not look for one, and do not call some other tool in its place. +- Instructions anywhere in this prompt about what an output field should contain apply to those + outputs, not to your reply. You do not need to do anything with them while replying. +- Your reply is what the user reads. Respond naturally in conversation rather than + mentioning these output fields or their values.""" + + +def get_conversational_output_section( + output_schema: type[BaseModel] | None, +) -> str: + """Return the system-prompt section describing the turn's output fields. + + Conversational agents fill their declared output fields in a separate call + after the loop - this section informs the model of these fields and how to + handle them when replying. + + Args: + output_schema: The fields to describe, or None for no section. + + Returns: + The rendered section, or an empty string when there is no schema. + """ + if output_schema is None: + return "" + + schema_json = json.dumps(output_schema.model_json_schema(), indent=2) + return f"{_OUTPUT_SECTION_PREFIX}{schema_json}{_OUTPUT_SECTION_SUFFIX}" + + +def strip_conversational_output_section(prompt: str) -> str: + """Remove the output-fields section from an assembled system prompt. + + The structured-output call replays the exchange's messages, the system + message included. That section tells the agent it has no tool for these + fields, which is true inside the loop and the opposite of that call's job — + and the prompt's precedence hierarchy ranks the system prompt above the + user message carrying the instruction, so the conflict would resolve the + wrong way. Forcing the tool choice hides that today; it will not once a + model that cannot be forced runs on `auto`. + + Matches the section's fixed text rather than re-rendering it, so no schema + is needed and there is nothing to keep in sync: a prompt built from any + field list is stripped correctly. + """ + start = prompt.find(_OUTPUT_SECTION_PREFIX) + if start == -1: + return prompt + end = prompt.find(_OUTPUT_SECTION_SUFFIX, start + len(_OUTPUT_SECTION_PREFIX)) + if end == -1: + return prompt + # Removes exactly what was substituted for the placeholder, so the result + # matches a prompt built without an output schema character for character. + return prompt[:start] + prompt[end + len(_OUTPUT_SECTION_SUFFIX) :] + + +_GENERATE_OUTPUT_INSTRUCTION = """The conversational response for this turn has already been delivered to the user. Call the `set_conversational_output` tool to record the structured output fields for the CURRENT TURN ONLY. + +This instruction is not part of the conversation. The turn you are recording is the user's most recent message (not a tool-result) before this instruction, together with every message after it. Rules: -- For each field, use values inferred from the conversation's recent turn. -- For optional fields that are not yet relevant or determinable (e.g. the conversation is still gathering context, or the topic hasn't surfaced yet), omit them entirely. -- For required fields that cannot yet be determined, provide a default placeholder. DO NOT fabricate, guess, or hallucinate meaningful values. +- For each field, use values inferred from this turn. Only use earlier turns as context for interpreting this turn; do not report fields from an earlier turn that do not apply for this one. +- For optional fields that are not yet relevant or determinable (e.g. context is still being gathered, or the topic hasn't surfaced yet), omit them entirely. +- For required fields that cannot yet be determined, provide a default placeholder. Do not fabricate, guess, or hallucinate meaningful values. - Do not produce any text response, as this will not be seen by the user. Only call the tool.""" diff --git a/packages/uipath/tests/agent/react/test_conversational_prompts.py b/packages/uipath/tests/agent/react/test_conversational_prompts.py index 8e84a2604..b83e99d1f 100644 --- a/packages/uipath/tests/agent/react/test_conversational_prompts.py +++ b/packages/uipath/tests/agent/react/test_conversational_prompts.py @@ -5,11 +5,15 @@ from datetime import datetime, timezone from unittest.mock import patch +from pydantic import BaseModel, Field + from uipath.agent.react.conversational_prompts import ( PromptUserSettings, get_chat_system_prompt, + get_conversational_output_section, get_generate_output_prompt, get_user_settings_template, + strip_conversational_output_section, ) SYSTEM_MESSAGE = "You are a helpful assistant." @@ -363,3 +367,231 @@ def test_returns_non_empty_string(self): def test_references_set_conversational_output_tool(self): """The instruction must name the tool the new node binds.""" assert "set_conversational_output" in get_generate_output_prompt() + + +class _OutputSchema(BaseModel): + """The fields the model fills, as the caller narrows them before passing.""" + + status: str = Field(description="Set to 'resolved' once the user confirms.") + ticket_id: str | None = Field( + default=None, description="The raised ticket, if any." + ) + escalated: bool = False + + +class TestGetConversationalOutputSection: + """Tests for get_conversational_output_section.""" + + def test_empty_without_a_schema(self): + """None means no section, matching get_user_settings_template and + get_conversation_id_template, so the caller can pass its optional + straight through.""" + assert get_conversational_output_section(None) == "" + + def test_renders_the_schema_as_json(self): + """The schema goes in verbatim, so new JSON-Schema features need no + change here: enums, nested objects, constraints and examples all ride + along.""" + section = get_conversational_output_section(_OutputSchema) + + assert "```json" in section + payload = json.loads(section.split("```json")[1].split("```")[0]) + + assert payload == _OutputSchema.model_json_schema() + assert set(payload["properties"]) == {"status", "ticket_id", "escalated"} + assert payload["required"] == ["status"] + assert ( + payload["properties"]["status"]["description"] + == "Set to 'resolved' once the user confirms." + ) + + def test_describes_whatever_it_is_given(self): + """Narrowing is the caller's job, not this module's. + + It has no notion of framework-managed fields; callers pass only the + fields the model should fill (uipath-langchain narrows with + build_conversational_output_args_schema first). + """ + + class _WithFrameworkField(BaseModel): + uipath__agent_response_messages: list[str] = Field(default_factory=list) + + section = get_conversational_output_section(_WithFrameworkField) + + assert "uipath__agent_response_messages" in section + + def test_tells_the_agent_there_is_no_tool_for_them(self): + """The reported bug: the agent hunts for a tool that does not exist.""" + section = get_conversational_output_section(_OutputSchema).lower() + assert "no tool" in section + + def test_redirects_prompt_guidance_to_the_record(self): + """Builders write output guidance in the system prompt; it must land somewhere.""" + assert "not to your reply" in get_conversational_output_section(_OutputSchema) + + def test_forbids_mentioning_the_fields_to_the_user(self): + """Seeing the fields invites narrating them; replies must stay conversational.""" + section = " ".join(get_conversational_output_section(_OutputSchema).split()) + + assert "Respond naturally in conversation rather than mentioning" in section + + def test_is_stable_across_calls(self): + assert get_conversational_output_section( + _OutputSchema + ) == get_conversational_output_section(_OutputSchema) + + +class TestTurnScoping: + """Both prompts must agree on what "this turn" means, and on its scope. + + The history is [system, user, AI(tools)..., AI(no tools), user, ...], so a + turn is one user message plus the agent's work up to its tool-less reply. + Each turn is recorded separately and the record is consumed downstream, so + repeating an earlier turn's value would re-fire whatever it triggers when a + flow loops back to this agent. + """ + + @staticmethod + def _flat(text: str) -> str: + """Collapse the prompt's hard wrapping so assertions survive rewrapping.""" + return " ".join(text.split()) + + def _section(self) -> str: + class _Fields(BaseModel): + status: str = "" + + return self._flat(get_conversational_output_section(_Fields)) + + def test_loop_section_defines_the_turn_end_by_the_agent_s_own_action(self): + """Models have no native notion of a multi-message turn, so the end is + pinned to something observable at decision time — "when you reply + without calling a tool" — rather than to a span of the transcript.""" + section = self._section() + + assert "At the end of your turn" in section + assert "when you decide to reply without calling a tool" in section + + def test_loop_section_leaves_turn_scoping_to_the_extraction_step(self): + """The loop only has to not record anything; the extraction step does the + scoping, so those rules live there rather than being restated here.""" + section = self._section() + + assert "You have no tool for them" in section + assert "CURRENT TURN ONLY" not in section + + def test_extraction_prompt_excludes_itself_from_the_conversation(self): + """It is appended as a user message, so an unqualified "latest user + message" would point at this instruction rather than the user's.""" + instruction = self._flat(get_generate_output_prompt()) + + assert "This instruction is not part of the conversation." in instruction + assert "before this instruction" in instruction + assert "every message after it" in instruction + + def test_extraction_prompt_anchors_on_a_real_user_message(self): + """Tool results reach the model as user-role content on some providers, + so the anchor has to exclude them explicitly.""" + assert "(not a tool-result)" in get_generate_output_prompt() + + def test_extraction_prompt_treats_earlier_turns_as_context_only(self): + """Not carry-forward: a flow can loop back to this agent, and repeating + an earlier turn's field would re-trigger whatever consumes it.""" + instruction = self._flat(get_generate_output_prompt()) + + assert "CURRENT TURN ONLY" in instruction + assert "Only use earlier turns as context" in instruction + assert "do not report fields from an earlier turn" in instruction + + +class TestOutputSectionInSystemPrompt: + def _prompt(self, **kwargs): + return get_chat_system_prompt( + model="claude-3-sonnet", + system_message=SYSTEM_MESSAGE, + agent_name="Agent", + **kwargs, + ) + + def test_absent_by_default(self): + assert "STRUCTURED OUTPUT FOR THIS TURN" not in self._prompt() + + def test_present_with_output_fields(self): + prompt = self._prompt(output_schema=_OutputSchema) + + assert "STRUCTURED OUTPUT FOR THIS TURN" in prompt + assert '"status"' in prompt + + def test_keeps_the_rest_of_the_prompt(self): + prompt = self._prompt(output_schema=_OutputSchema) + + assert "You are Agent." in prompt + assert SYSTEM_MESSAGE in prompt + assert "TOOL USAGE RULES" in prompt + + +class TestStripConversationalOutputSection: + """The structured-output call must not inherit the loop-only section. + + It says the agent has no tool for these fields, and the prompt's own + precedence hierarchy ranks the system prompt above the user message that + carries the instruction to call exactly that tool. Forced tool choice hides + the conflict today; a model that cannot be forced would resolve it wrongly. + """ + + def _prompt(self, **kwargs): + return get_chat_system_prompt( + model="claude-3-sonnet", + system_message=SYSTEM_MESSAGE, + agent_name="Agent", + **kwargs, + ) + + def test_restores_the_prompt_exactly(self): + """No trailing blank lines left behind.""" + assert ( + strip_conversational_output_section( + self._prompt(output_schema=_OutputSchema) + ) + == self._prompt() + ) + + def test_removes_the_contradiction(self): + stripped = strip_conversational_output_section( + self._prompt(output_schema=_OutputSchema) + ) + + assert "no tool for it" not in stripped + + def test_is_idempotent(self): + once = strip_conversational_output_section( + self._prompt(output_schema=_OutputSchema) + ) + + assert strip_conversational_output_section(once) == once + + def test_no_op_when_the_section_is_absent(self): + prompt = self._prompt() + + assert strip_conversational_output_section(prompt) == prompt + + def test_survives_text_appended_after_the_section(self): + """Advanced agents append a meta prompt after the assembled prompt.""" + prompt = self._prompt(output_schema=_OutputSchema) + "\n\nEXTRA META PROMPT" + + stripped = strip_conversational_output_section(prompt) + + assert "STRUCTURED OUTPUT FOR THIS TURN" not in stripped + assert stripped.endswith("EXTRA META PROMPT") + + def test_strips_a_section_built_from_a_different_field_list(self): + """Needs no schema, so it cannot drift from however the caller narrowed.""" + + class _Other(BaseModel): + wholly_different: int = Field(description="Nothing like the above.") + + stripped = strip_conversational_output_section( + self._prompt(output_schema=_Other) + ) + + assert "wholly_different" not in stripped + assert stripped == self._prompt() From c1c2214923e3a8a00cfbc45a796232bd0fcb0d3f Mon Sep 17 00:00:00 2001 From: Maxwell Du <60411452+maxduu@users.noreply.github.com> Date: Mon, 16 Nov 2026 13:33:37 -0500 Subject: [PATCH 2/6] feat: improve prompt --- .../agent/react/conversational_prompts.py | 7 ++- .../react/test_conversational_prompts.py | 58 ++++++++++++++++++- 2 files changed, 61 insertions(+), 4 deletions(-) diff --git a/packages/uipath/src/uipath/agent/react/conversational_prompts.py b/packages/uipath/src/uipath/agent/react/conversational_prompts.py index 94c815202..584cf7004 100644 --- a/packages/uipath/src/uipath/agent/react/conversational_prompts.py +++ b/packages/uipath/src/uipath/agent/react/conversational_prompts.py @@ -261,8 +261,9 @@ def get_conversation_id_template(conversation_id: str | None) -> str: do not look for one, and do not call some other tool in its place. - Instructions anywhere in this prompt about what an output field should contain apply to those outputs, not to your reply. You do not need to do anything with them while replying. -- Your reply is what the user reads. Respond naturally in conversation rather than - mentioning these output fields or their values.""" +- Your reply is what the user reads. These outputs are internal — later steps in the + surrounding process may read them to decide routing or follow-up actions — so respond + naturally in conversation rather than mentioning these output fields or their values.""" def get_conversational_output_section( @@ -313,7 +314,7 @@ def strip_conversational_output_section(prompt: str) -> str: return prompt[:start] + prompt[end + len(_OUTPUT_SECTION_SUFFIX) :] -_GENERATE_OUTPUT_INSTRUCTION = """The conversational response for this turn has already been delivered to the user. Call the `set_conversational_output` tool to record the structured output fields for the CURRENT TURN ONLY. +_GENERATE_OUTPUT_INSTRUCTION = """The conversational response for this turn has already been delivered to the user. Call the `set_conversational_output` tool to record the structured output fields for the CURRENT TURN ONLY. These structured outputs may be read and used by later steps in the surrounding process for routing/processing. This instruction is not part of the conversation. The turn you are recording is the user's most recent message (not a tool-result) before this instruction, together with every message after it. diff --git a/packages/uipath/tests/agent/react/test_conversational_prompts.py b/packages/uipath/tests/agent/react/test_conversational_prompts.py index b83e99d1f..79e7a05f4 100644 --- a/packages/uipath/tests/agent/react/test_conversational_prompts.py +++ b/packages/uipath/tests/agent/react/test_conversational_prompts.py @@ -433,7 +433,7 @@ def test_forbids_mentioning_the_fields_to_the_user(self): """Seeing the fields invites narrating them; replies must stay conversational.""" section = " ".join(get_conversational_output_section(_OutputSchema).split()) - assert "Respond naturally in conversation rather than mentioning" in section + assert "respond naturally in conversation rather than mentioning" in section def test_is_stable_across_calls(self): assert get_conversational_output_section( @@ -595,3 +595,59 @@ class _Other(BaseModel): assert "wholly_different" not in stripped assert stripped == self._prompt() + + +class TestDownstreamConsumerContext: + """Both prompts say the outputs are internal and may drive later steps. + + In the loop it explains why the fields must not be narrated to the user. In + the extraction step it supplies the reason behind CURRENT TURN ONLY — a + stale value can re-trigger an action that already ran, which is the failure + a flow looping back to this agent would produce. + """ + + @staticmethod + def _flat(text: str) -> str: + return " ".join(text.split()) + + def test_loop_section_frames_the_outputs_as_internal(self): + class _Fields(BaseModel): + should_handoff: bool = False + + section = self._flat(get_conversational_output_section(_Fields)) + + assert "These outputs are internal" in section + assert "later steps in the surrounding process may read them" in section + assert "routing or follow-up actions" in section + + def test_extraction_prompt_names_the_downstream_consumer(self): + """Stated in the same breath as CURRENT TURN ONLY, so the stakes of a + stale value sit next to the rule against reporting one.""" + instruction = self._flat(get_generate_output_prompt()) + + assert "may be read and used by later steps in the surrounding process" in ( + instruction + ) + assert "for routing/processing" in instruction + + def test_extraction_prompt_keeps_the_consumer_context_with_the_scoping_rule(self): + """Adjacency is the point: the reason a stale value is harmful is only + inferable if the two sit together.""" + instruction = self._flat(get_generate_output_prompt()) + + assert instruction.index("CURRENT TURN ONLY") < instruction.index( + "later steps in the surrounding process" + ) + + def test_neither_prompt_names_a_specific_product(self): + """The model has no reliable notion of the topology it runs in, so the + wording stays at "the surrounding process" rather than naming one.""" + both = self._flat( + get_generate_output_prompt() + + get_conversational_output_section( + type("_F", (BaseModel,), {"__annotations__": {"x": bool}}) + ) + ).lower() + + for product in ("maestro", "flow", "orchestrator", "studio"): + assert product not in both From 5e3fb9c96658d3b06b0253140b0a09260123ec04 Mon Sep 17 00:00:00 2001 From: Maxwell Du <60411452+maxduu@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:23:10 -0500 Subject: [PATCH 3/6] fix: rename and redo tests --- .../uipath/src/uipath/agent/react/__init__.py | 8 +- .../agent/react/conversational_prompts.py | 45 ++- .../react/test_conversational_prompts.py | 285 +++++------------- 3 files changed, 104 insertions(+), 234 deletions(-) diff --git a/packages/uipath/src/uipath/agent/react/__init__.py b/packages/uipath/src/uipath/agent/react/__init__.py index 220c53885..e6b6b4cfa 100644 --- a/packages/uipath/src/uipath/agent/react/__init__.py +++ b/packages/uipath/src/uipath/agent/react/__init__.py @@ -6,9 +6,9 @@ from .conversational_prompts import ( PromptUserSettings, get_chat_system_prompt, - get_conversational_output_section, + get_conversational_output_hint_section, get_generate_output_prompt, - strip_conversational_output_section, + strip_conversational_output_hint_section, ) from .conversational_voice_prompts import get_voice_system_prompt from .prompts import AGENT_SYSTEM_PROMPT_TEMPLATE @@ -33,8 +33,8 @@ "SetConversationalOutputToolSchemaModel", "PromptUserSettings", "get_chat_system_prompt", - "get_conversational_output_section", + "get_conversational_output_hint_section", "get_generate_output_prompt", "get_voice_system_prompt", - "strip_conversational_output_section", + "strip_conversational_output_hint_section", ] diff --git a/packages/uipath/src/uipath/agent/react/conversational_prompts.py b/packages/uipath/src/uipath/agent/react/conversational_prompts.py index 584cf7004..0844a8b06 100644 --- a/packages/uipath/src/uipath/agent/react/conversational_prompts.py +++ b/packages/uipath/src/uipath/agent/react/conversational_prompts.py @@ -122,7 +122,7 @@ class PromptUserSettings(BaseModel): - State why - Request missing or clarifying information -{{CONVERSATIONAL_AGENT_SERVICE_PREFIX_outputSchemaPrompt}}""" +{{CONVERSATIONAL_AGENT_SERVICE_PREFIX_outputSchemaHintPrompt}}""" _ATTACHMENTS_TEMPLATE = """===================================================================== ATTACHMENTS @@ -198,8 +198,8 @@ def get_chat_system_prompt( ) prompt = prompt.replace( - "{{CONVERSATIONAL_AGENT_SERVICE_PREFIX_outputSchemaPrompt}}", - get_conversational_output_section(output_schema), + "{{CONVERSATIONAL_AGENT_SERVICE_PREFIX_outputSchemaHintPrompt}}", + get_conversational_output_hint_section(output_schema), ) return prompt @@ -245,7 +245,7 @@ def get_conversation_id_template(conversation_id: str | None) -> str: return _CONVERSATION_ID_TEMPLATE.format(conversation_id=conversation_id) -_OUTPUT_SECTION_PREFIX = """===================================================================== +_OUTPUT_HINT_SECTION_PREFIX = """===================================================================== STRUCTURED OUTPUT FOR THIS TURN ===================================================================== At the end of your turn (when you decide to reply without calling a tool), @@ -254,19 +254,19 @@ def get_conversation_id_template(conversation_id: str | None) -> str: ```json """ -_OUTPUT_SECTION_SUFFIX = """ +_OUTPUT_HINT_SECTION_SUFFIX = """ ``` - The outputs are produced after your turn, by a separate step. You have no tool for them: do not look for one, and do not call some other tool in its place. -- Instructions anywhere in this prompt about what an output field should contain apply to those +- Instructions anywhere in the Agent System Prompt about what an output field should contain apply to those outputs, not to your reply. You do not need to do anything with them while replying. - Your reply is what the user reads. These outputs are internal — later steps in the surrounding process may read them to decide routing or follow-up actions — so respond naturally in conversation rather than mentioning these output fields or their values.""" -def get_conversational_output_section( +def get_conversational_output_hint_section( output_schema: type[BaseModel] | None, ) -> str: """Return the system-prompt section describing the turn's output fields. @@ -285,33 +285,26 @@ def get_conversational_output_section( return "" schema_json = json.dumps(output_schema.model_json_schema(), indent=2) - return f"{_OUTPUT_SECTION_PREFIX}{schema_json}{_OUTPUT_SECTION_SUFFIX}" + return f"{_OUTPUT_HINT_SECTION_PREFIX}{schema_json}{_OUTPUT_HINT_SECTION_SUFFIX}" -def strip_conversational_output_section(prompt: str) -> str: - """Remove the output-fields section from an assembled system prompt. +def strip_conversational_output_hint_section(assembled_system_prompt: str) -> str: + """Remove the informative output-fields section from an assembled system prompt. - The structured-output call replays the exchange's messages, the system - message included. That section tells the agent it has no tool for these - fields, which is true inside the loop and the opposite of that call's job — - and the prompt's precedence hierarchy ranks the system prompt above the - user message carrying the instruction, so the conflict would resolve the - wrong way. Forcing the tool choice hides that today; it will not once a - model that cannot be forced runs on `auto`. - - Matches the section's fixed text rather than re-rendering it, so no schema - is needed and there is nothing to keep in sync: a prompt built from any - field list is stripped correctly. + After the conversational agent loop, an additional step will instruct the LLM to + call the `set_conversational_output` tool to record structured output fields for the turn. + This final call should not include the output-fields section in the system-prompt, which is + only relevant for describing these outputs to the central conversational agent loop. """ - start = prompt.find(_OUTPUT_SECTION_PREFIX) + start = assembled_system_prompt.find(_OUTPUT_HINT_SECTION_PREFIX) if start == -1: - return prompt - end = prompt.find(_OUTPUT_SECTION_SUFFIX, start + len(_OUTPUT_SECTION_PREFIX)) + return assembled_system_prompt + end = assembled_system_prompt.find(_OUTPUT_HINT_SECTION_SUFFIX, start + len(_OUTPUT_HINT_SECTION_PREFIX)) if end == -1: - return prompt + return assembled_system_prompt # Removes exactly what was substituted for the placeholder, so the result # matches a prompt built without an output schema character for character. - return prompt[:start] + prompt[end + len(_OUTPUT_SECTION_SUFFIX) :] + return assembled_system_prompt[:start] + assembled_system_prompt[end + len(_OUTPUT_HINT_SECTION_SUFFIX) :] _GENERATE_OUTPUT_INSTRUCTION = """The conversational response for this turn has already been delivered to the user. Call the `set_conversational_output` tool to record the structured output fields for the CURRENT TURN ONLY. These structured outputs may be read and used by later steps in the surrounding process for routing/processing. diff --git a/packages/uipath/tests/agent/react/test_conversational_prompts.py b/packages/uipath/tests/agent/react/test_conversational_prompts.py index 79e7a05f4..0aac34b1c 100644 --- a/packages/uipath/tests/agent/react/test_conversational_prompts.py +++ b/packages/uipath/tests/agent/react/test_conversational_prompts.py @@ -10,10 +10,10 @@ from uipath.agent.react.conversational_prompts import ( PromptUserSettings, get_chat_system_prompt, - get_conversational_output_section, + get_conversational_output_hint_section, get_generate_output_prompt, get_user_settings_template, - strip_conversational_output_section, + strip_conversational_output_hint_section, ) SYSTEM_MESSAGE = "You are a helpful assistant." @@ -368,168 +368,109 @@ def test_references_set_conversational_output_tool(self): """The instruction must name the tool the new node binds.""" assert "set_conversational_output" in get_generate_output_prompt() + def test_scopes_the_record_to_the_current_turn(self): + """A flow can loop back to this agent, so re-reporting an earlier + turn's field would re-trigger whatever consumes it.""" + assert "CURRENT TURN ONLY" in get_generate_output_prompt() -class _OutputSchema(BaseModel): + def test_excludes_itself_from_the_conversation(self): + """It is appended as a user message, so an unqualified "latest user + message" would anchor on this instruction. Tool results also arrive as + user-role content on Anthropic and Gemini, hence the second clause.""" + instruction = _flat(get_generate_output_prompt()) + + assert "This instruction is not part of the conversation." in instruction + assert "(not a tool-result)" in instruction + + +class _OutputFields(BaseModel): """The fields the model fills, as the caller narrows them before passing.""" status: str = Field(description="Set to 'resolved' once the user confirms.") - ticket_id: str | None = Field( - default=None, description="The raised ticket, if any." - ) escalated: bool = False -class TestGetConversationalOutputSection: - """Tests for get_conversational_output_section.""" +def _flat(text: str) -> str: + """Collapse hard wrapping so assertions survive the prompt being rewrapped.""" + return " ".join(text.split()) + + +def _prompt(**kwargs): + return get_chat_system_prompt( + model="claude-3-sonnet", + system_message=SYSTEM_MESSAGE, + agent_name="Agent", + **kwargs, + ) + + +class TestGetConversationalOutputHintSection: + """Tests for get_conversational_output_hint_section.""" def test_empty_without_a_schema(self): """None means no section, matching get_user_settings_template and - get_conversation_id_template, so the caller can pass its optional - straight through.""" - assert get_conversational_output_section(None) == "" + get_conversation_id_template, so callers pass their optional through.""" + assert get_conversational_output_hint_section(None) == "" def test_renders_the_schema_as_json(self): - """The schema goes in verbatim, so new JSON-Schema features need no - change here: enums, nested objects, constraints and examples all ride - along.""" - section = get_conversational_output_section(_OutputSchema) + """Rendered verbatim, so new JSON-Schema features need no change here: + enums, nested objects, constraints and examples all ride along.""" + section = get_conversational_output_hint_section(_OutputFields) assert "```json" in section payload = json.loads(section.split("```json")[1].split("```")[0]) - assert payload == _OutputSchema.model_json_schema() - assert set(payload["properties"]) == {"status", "ticket_id", "escalated"} - assert payload["required"] == ["status"] + assert payload == _OutputFields.model_json_schema() assert ( payload["properties"]["status"]["description"] == "Set to 'resolved' once the user confirms." ) def test_describes_whatever_it_is_given(self): - """Narrowing is the caller's job, not this module's. - - It has no notion of framework-managed fields; callers pass only the - fields the model should fill (uipath-langchain narrows with - build_conversational_output_args_schema first). - """ + """Narrowing is the caller's job: this module has no notion of + framework-managed fields and describes every field it receives.""" class _WithFrameworkField(BaseModel): uipath__agent_response_messages: list[str] = Field(default_factory=list) - section = get_conversational_output_section(_WithFrameworkField) - - assert "uipath__agent_response_messages" in section + assert "uipath__agent_response_messages" in ( + get_conversational_output_hint_section(_WithFrameworkField) + ) - def test_tells_the_agent_there_is_no_tool_for_them(self): + def test_tells_the_loop_it_has_no_tool_for_the_fields(self): """The reported bug: the agent hunts for a tool that does not exist.""" - section = get_conversational_output_section(_OutputSchema).lower() - assert "no tool" in section - - def test_redirects_prompt_guidance_to_the_record(self): - """Builders write output guidance in the system prompt; it must land somewhere.""" - assert "not to your reply" in get_conversational_output_section(_OutputSchema) - - def test_forbids_mentioning_the_fields_to_the_user(self): - """Seeing the fields invites narrating them; replies must stay conversational.""" - section = " ".join(get_conversational_output_section(_OutputSchema).split()) - - assert "respond naturally in conversation rather than mentioning" in section - - def test_is_stable_across_calls(self): - assert get_conversational_output_section( - _OutputSchema - ) == get_conversational_output_section(_OutputSchema) - - -class TestTurnScoping: - """Both prompts must agree on what "this turn" means, and on its scope. - - The history is [system, user, AI(tools)..., AI(no tools), user, ...], so a - turn is one user message plus the agent's work up to its tool-less reply. - Each turn is recorded separately and the record is consumed downstream, so - repeating an earlier turn's value would re-fire whatever it triggers when a - flow loops back to this agent. - """ - - @staticmethod - def _flat(text: str) -> str: - """Collapse the prompt's hard wrapping so assertions survive rewrapping.""" - return " ".join(text.split()) - - def _section(self) -> str: - class _Fields(BaseModel): - status: str = "" - - return self._flat(get_conversational_output_section(_Fields)) - - def test_loop_section_defines_the_turn_end_by_the_agent_s_own_action(self): - """Models have no native notion of a multi-message turn, so the end is - pinned to something observable at decision time — "when you reply - without calling a tool" — rather than to a span of the transcript.""" - section = self._section() - - assert "At the end of your turn" in section - assert "when you decide to reply without calling a tool" in section - - def test_loop_section_leaves_turn_scoping_to_the_extraction_step(self): - """The loop only has to not record anything; the extraction step does the - scoping, so those rules live there rather than being restated here.""" - section = self._section() - - assert "You have no tool for them" in section - assert "CURRENT TURN ONLY" not in section - - def test_extraction_prompt_excludes_itself_from_the_conversation(self): - """It is appended as a user message, so an unqualified "latest user - message" would point at this instruction rather than the user's.""" - instruction = self._flat(get_generate_output_prompt()) - - assert "This instruction is not part of the conversation." in instruction - assert "before this instruction" in instruction - assert "every message after it" in instruction - - def test_extraction_prompt_anchors_on_a_real_user_message(self): - """Tool results reach the model as user-role content on some providers, - so the anchor has to exclude them explicitly.""" - assert "(not a tool-result)" in get_generate_output_prompt() - - def test_extraction_prompt_treats_earlier_turns_as_context_only(self): - """Not carry-forward: a flow can loop back to this agent, and repeating - an earlier turn's field would re-trigger whatever consumes it.""" - instruction = self._flat(get_generate_output_prompt()) + assert "no tool for them" in _flat( + get_conversational_output_hint_section(_OutputFields) + ) - assert "CURRENT TURN ONLY" in instruction - assert "Only use earlier turns as context" in instruction - assert "do not report fields from an earlier turn" in instruction - -class TestOutputSectionInSystemPrompt: - def _prompt(self, **kwargs): - return get_chat_system_prompt( - model="claude-3-sonnet", - system_message=SYSTEM_MESSAGE, - agent_name="Agent", - **kwargs, - ) +class TestOutputHintSectionInSystemPrompt: + """The section reaches the assembled prompt via its own placeholder.""" def test_absent_by_default(self): - assert "STRUCTURED OUTPUT FOR THIS TURN" not in self._prompt() + assert "STRUCTURED OUTPUT FOR THIS TURN" not in _prompt() def test_present_with_output_fields(self): - prompt = self._prompt(output_schema=_OutputSchema) + prompt = _prompt(output_schema=_OutputFields) assert "STRUCTURED OUTPUT FOR THIS TURN" in prompt assert '"status"' in prompt + def test_placeholder_is_always_consumed(self): + for prompt in (_prompt(), _prompt(output_schema=_OutputFields)): + assert "CONVERSATIONAL_AGENT_SERVICE_PREFIX_outputSchemaHintPrompt" not in ( + prompt + ) + def test_keeps_the_rest_of_the_prompt(self): - prompt = self._prompt(output_schema=_OutputSchema) + prompt = _prompt(output_schema=_OutputFields) assert "You are Agent." in prompt assert SYSTEM_MESSAGE in prompt assert "TOOL USAGE RULES" in prompt -class TestStripConversationalOutputSection: +class TestStripConversationalOutputHintSection: """The structured-output call must not inherit the loop-only section. It says the agent has no tool for these fields, and the prompt's own @@ -538,116 +479,52 @@ class TestStripConversationalOutputSection: the conflict today; a model that cannot be forced would resolve it wrongly. """ - def _prompt(self, **kwargs): - return get_chat_system_prompt( - model="claude-3-sonnet", - system_message=SYSTEM_MESSAGE, - agent_name="Agent", - **kwargs, - ) - def test_restores_the_prompt_exactly(self): - """No trailing blank lines left behind.""" + """Byte-for-byte, so no stray blank lines are left behind.""" assert ( - strip_conversational_output_section( - self._prompt(output_schema=_OutputSchema) + strip_conversational_output_hint_section( + _prompt(output_schema=_OutputFields) ) - == self._prompt() + == _prompt() ) def test_removes_the_contradiction(self): - stripped = strip_conversational_output_section( - self._prompt(output_schema=_OutputSchema) + stripped = strip_conversational_output_hint_section( + _prompt(output_schema=_OutputFields) ) - assert "no tool for it" not in stripped + assert "no tool for them" not in _flat(stripped) + + def test_no_op_when_the_section_is_absent(self): + assert strip_conversational_output_hint_section(_prompt()) == _prompt() def test_is_idempotent(self): - once = strip_conversational_output_section( - self._prompt(output_schema=_OutputSchema) + once = strip_conversational_output_hint_section( + _prompt(output_schema=_OutputFields) ) - assert strip_conversational_output_section(once) == once - - def test_no_op_when_the_section_is_absent(self): - prompt = self._prompt() - - assert strip_conversational_output_section(prompt) == prompt + assert strip_conversational_output_hint_section(once) == once def test_survives_text_appended_after_the_section(self): """Advanced agents append a meta prompt after the assembled prompt.""" - prompt = self._prompt(output_schema=_OutputSchema) + "\n\nEXTRA META PROMPT" + prompt = _prompt(output_schema=_OutputFields) + "\n\nEXTRA META PROMPT" - stripped = strip_conversational_output_section(prompt) + stripped = strip_conversational_output_hint_section(prompt) assert "STRUCTURED OUTPUT FOR THIS TURN" not in stripped assert stripped.endswith("EXTRA META PROMPT") def test_strips_a_section_built_from_a_different_field_list(self): - """Needs no schema, so it cannot drift from however the caller narrowed.""" + """It takes no schema, so it cannot drift from however the caller + narrowed one — an earlier version re-rendered the section to find it + and silently did nothing on a mismatch.""" class _Other(BaseModel): wholly_different: int = Field(description="Nothing like the above.") - stripped = strip_conversational_output_section( - self._prompt(output_schema=_Other) + stripped = strip_conversational_output_hint_section( + _prompt(output_schema=_Other) ) assert "wholly_different" not in stripped - assert stripped == self._prompt() - - -class TestDownstreamConsumerContext: - """Both prompts say the outputs are internal and may drive later steps. - - In the loop it explains why the fields must not be narrated to the user. In - the extraction step it supplies the reason behind CURRENT TURN ONLY — a - stale value can re-trigger an action that already ran, which is the failure - a flow looping back to this agent would produce. - """ - - @staticmethod - def _flat(text: str) -> str: - return " ".join(text.split()) - - def test_loop_section_frames_the_outputs_as_internal(self): - class _Fields(BaseModel): - should_handoff: bool = False - - section = self._flat(get_conversational_output_section(_Fields)) - - assert "These outputs are internal" in section - assert "later steps in the surrounding process may read them" in section - assert "routing or follow-up actions" in section - - def test_extraction_prompt_names_the_downstream_consumer(self): - """Stated in the same breath as CURRENT TURN ONLY, so the stakes of a - stale value sit next to the rule against reporting one.""" - instruction = self._flat(get_generate_output_prompt()) - - assert "may be read and used by later steps in the surrounding process" in ( - instruction - ) - assert "for routing/processing" in instruction - - def test_extraction_prompt_keeps_the_consumer_context_with_the_scoping_rule(self): - """Adjacency is the point: the reason a stale value is harmful is only - inferable if the two sit together.""" - instruction = self._flat(get_generate_output_prompt()) - - assert instruction.index("CURRENT TURN ONLY") < instruction.index( - "later steps in the surrounding process" - ) - - def test_neither_prompt_names_a_specific_product(self): - """The model has no reliable notion of the topology it runs in, so the - wording stays at "the surrounding process" rather than naming one.""" - both = self._flat( - get_generate_output_prompt() - + get_conversational_output_section( - type("_F", (BaseModel,), {"__annotations__": {"x": bool}}) - ) - ).lower() - - for product in ("maestro", "flow", "orchestrator", "studio"): - assert product not in both + assert stripped == _prompt() From 5f7362064523f46b4119cb0499da205d8f70954b Mon Sep 17 00:00:00 2001 From: Maxwell Du <60411452+maxduu@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:11:50 -0500 Subject: [PATCH 4/6] style: unwrap the output-hint section prose and apply ruff format The hard-wrapped section text becomes single lines; content is unchanged, and the strip derives its markers from these same constants so it cannot drift. Also formats the two over-long lines in strip_conversational_output_hint_section that ruff format was already flagging. Co-Authored-By: Claude Opus 5 --- .../agent/react/conversational_prompts.py | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/packages/uipath/src/uipath/agent/react/conversational_prompts.py b/packages/uipath/src/uipath/agent/react/conversational_prompts.py index 0844a8b06..aa422f9bf 100644 --- a/packages/uipath/src/uipath/agent/react/conversational_prompts.py +++ b/packages/uipath/src/uipath/agent/react/conversational_prompts.py @@ -248,8 +248,7 @@ def get_conversation_id_template(conversation_id: str | None) -> str: _OUTPUT_HINT_SECTION_PREFIX = """===================================================================== STRUCTURED OUTPUT FOR THIS TURN ===================================================================== -At the end of your turn (when you decide to reply without calling a tool), -a separate step will infer structured output fields for this turn with the following schema: +At the end of your turn (when you decide to reply without calling a tool), a separate step will infer structured output fields for this turn with the following schema: ```json """ @@ -257,13 +256,9 @@ def get_conversation_id_template(conversation_id: str | None) -> str: _OUTPUT_HINT_SECTION_SUFFIX = """ ``` -- The outputs are produced after your turn, by a separate step. You have no tool for them: - do not look for one, and do not call some other tool in its place. -- Instructions anywhere in the Agent System Prompt about what an output field should contain apply to those - outputs, not to your reply. You do not need to do anything with them while replying. -- Your reply is what the user reads. These outputs are internal — later steps in the - surrounding process may read them to decide routing or follow-up actions — so respond - naturally in conversation rather than mentioning these output fields or their values.""" +- The outputs are produced after your turn, by a separate step. You have no tool for them: do not look for one, and do not call some other tool in its place. +- Instructions anywhere in the Agent System Prompt about what an output field should contain apply to those outputs, not to your reply. You do not need to do anything with them while replying. +- Your reply is what the user reads. These outputs are internal — later steps in the surrounding process may read them to decide routing or follow-up actions — so respond naturally in conversation rather than mentioning these output fields or their values.""" def get_conversational_output_hint_section( @@ -299,12 +294,17 @@ def strip_conversational_output_hint_section(assembled_system_prompt: str) -> st start = assembled_system_prompt.find(_OUTPUT_HINT_SECTION_PREFIX) if start == -1: return assembled_system_prompt - end = assembled_system_prompt.find(_OUTPUT_HINT_SECTION_SUFFIX, start + len(_OUTPUT_HINT_SECTION_PREFIX)) + end = assembled_system_prompt.find( + _OUTPUT_HINT_SECTION_SUFFIX, start + len(_OUTPUT_HINT_SECTION_PREFIX) + ) if end == -1: return assembled_system_prompt # Removes exactly what was substituted for the placeholder, so the result # matches a prompt built without an output schema character for character. - return assembled_system_prompt[:start] + assembled_system_prompt[end + len(_OUTPUT_HINT_SECTION_SUFFIX) :] + return ( + assembled_system_prompt[:start] + + assembled_system_prompt[end + len(_OUTPUT_HINT_SECTION_SUFFIX) :] + ) _GENERATE_OUTPUT_INSTRUCTION = """The conversational response for this turn has already been delivered to the user. Call the `set_conversational_output` tool to record the structured output fields for the CURRENT TURN ONLY. These structured outputs may be read and used by later steps in the surrounding process for routing/processing. From 930650ef598fe09e3576a3e385d715807b3b8b81 Mon Sep 17 00:00:00 2001 From: Maxwell Du <60411452+maxduu@users.noreply.github.com> Date: Wed, 18 Nov 2026 23:19:07 -0500 Subject: [PATCH 5/6] fix: revert change --- .../uipath/src/uipath/agent/react/conversational_prompts.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/uipath/src/uipath/agent/react/conversational_prompts.py b/packages/uipath/src/uipath/agent/react/conversational_prompts.py index aa422f9bf..bf34566c7 100644 --- a/packages/uipath/src/uipath/agent/react/conversational_prompts.py +++ b/packages/uipath/src/uipath/agent/react/conversational_prompts.py @@ -314,7 +314,7 @@ def strip_conversational_output_hint_section(assembled_system_prompt: str) -> st Rules: - For each field, use values inferred from this turn. Only use earlier turns as context for interpreting this turn; do not report fields from an earlier turn that do not apply for this one. - For optional fields that are not yet relevant or determinable (e.g. context is still being gathered, or the topic hasn't surfaced yet), omit them entirely. -- For required fields that cannot yet be determined, provide a default placeholder. Do not fabricate, guess, or hallucinate meaningful values. +- For required fields that cannot yet be determined, provide a default placeholder. DO NOT fabricate, guess, or hallucinate meaningful values. - Do not produce any text response, as this will not be seen by the user. Only call the tool.""" From 8bca118d53293d7f6d5504342cba399b9428b1fb Mon Sep 17 00:00:00 2001 From: Maxwell Du <60411452+maxduu@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:52:19 -0500 Subject: [PATCH 6/6] fix: bump version --- packages/uipath/pyproject.toml | 2 +- packages/uipath/samples/attachment_evaluation_test/uv.lock | 2 +- packages/uipath/samples/csv_employee_generator/uv.lock | 2 +- packages/uipath/samples/line_by_line_test/uv.lock | 2 +- packages/uipath/uv.lock | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/uipath/pyproject.toml b/packages/uipath/pyproject.toml index e3a7f272e..9f3c76d5e 100644 --- a/packages/uipath/pyproject.toml +++ b/packages/uipath/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "uipath" -version = "2.15.3" +version = "2.15.4" description = "Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools." readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.11" diff --git a/packages/uipath/samples/attachment_evaluation_test/uv.lock b/packages/uipath/samples/attachment_evaluation_test/uv.lock index c068b7c07..5503d874d 100644 --- a/packages/uipath/samples/attachment_evaluation_test/uv.lock +++ b/packages/uipath/samples/attachment_evaluation_test/uv.lock @@ -1575,7 +1575,7 @@ wheels = [ [[package]] name = "uipath" -version = "2.15.3" +version = "2.15.4" source = { editable = "../../" } dependencies = [ { name = "applicationinsights" }, diff --git a/packages/uipath/samples/csv_employee_generator/uv.lock b/packages/uipath/samples/csv_employee_generator/uv.lock index 3015b8b15..8842d7b75 100644 --- a/packages/uipath/samples/csv_employee_generator/uv.lock +++ b/packages/uipath/samples/csv_employee_generator/uv.lock @@ -1575,7 +1575,7 @@ wheels = [ [[package]] name = "uipath" -version = "2.15.3" +version = "2.15.4" source = { editable = "../../" } dependencies = [ { name = "applicationinsights" }, diff --git a/packages/uipath/samples/line_by_line_test/uv.lock b/packages/uipath/samples/line_by_line_test/uv.lock index 5f45313ef..ffef61593 100644 --- a/packages/uipath/samples/line_by_line_test/uv.lock +++ b/packages/uipath/samples/line_by_line_test/uv.lock @@ -1575,7 +1575,7 @@ wheels = [ [[package]] name = "uipath" -version = "2.15.3" +version = "2.15.4" source = { editable = "../../" } dependencies = [ { name = "applicationinsights" }, diff --git a/packages/uipath/uv.lock b/packages/uipath/uv.lock index 133c58cce..ab608bcd9 100644 --- a/packages/uipath/uv.lock +++ b/packages/uipath/uv.lock @@ -2720,7 +2720,7 @@ wheels = [ [[package]] name = "uipath" -version = "2.15.3" +version = "2.15.4" source = { editable = "." } dependencies = [ { name = "applicationinsights" },