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/src/uipath/agent/react/__init__.py b/packages/uipath/src/uipath/agent/react/__init__.py index 539f062b6..e6b6b4cfa 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_hint_section, get_generate_output_prompt, + strip_conversational_output_hint_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_hint_section", "get_generate_output_prompt", "get_voice_system_prompt", + "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 18ace179f..bf34566c7 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_outputSchemaHintPrompt}}""" _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_outputSchemaHintPrompt}}", + get_conversational_output_hint_section(output_schema), + ) + return prompt @@ -236,11 +245,75 @@ 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_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: + +```json +""" + +_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.""" + + +def get_conversational_output_hint_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_HINT_SECTION_PREFIX}{schema_json}{_OUTPUT_HINT_SECTION_SUFFIX}" + + +def strip_conversational_output_hint_section(assembled_system_prompt: str) -> str: + """Remove the informative output-fields section from an assembled system prompt. + + 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 = 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) + ) + 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) :] + ) + + +_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. 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 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..0aac34b1c 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_hint_section, get_generate_output_prompt, get_user_settings_template, + strip_conversational_output_hint_section, ) SYSTEM_MESSAGE = "You are a helpful assistant." @@ -363,3 +367,164 @@ 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() + + 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() + + 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.") + escalated: bool = False + + +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 callers pass their optional through.""" + assert get_conversational_output_hint_section(None) == "" + + def test_renders_the_schema_as_json(self): + """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 == _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: 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) + + assert "uipath__agent_response_messages" in ( + get_conversational_output_hint_section(_WithFrameworkField) + ) + + 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.""" + assert "no tool for them" in _flat( + get_conversational_output_hint_section(_OutputFields) + ) + + +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 _prompt() + + def test_present_with_output_fields(self): + 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 = _prompt(output_schema=_OutputFields) + + assert "You are Agent." in prompt + assert SYSTEM_MESSAGE in prompt + assert "TOOL USAGE RULES" in prompt + + +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 + 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 test_restores_the_prompt_exactly(self): + """Byte-for-byte, so no stray blank lines are left behind.""" + assert ( + strip_conversational_output_hint_section( + _prompt(output_schema=_OutputFields) + ) + == _prompt() + ) + + def test_removes_the_contradiction(self): + stripped = strip_conversational_output_hint_section( + _prompt(output_schema=_OutputFields) + ) + + 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_hint_section( + _prompt(output_schema=_OutputFields) + ) + + 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 = _prompt(output_schema=_OutputFields) + "\n\nEXTRA META 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): + """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_hint_section( + _prompt(output_schema=_Other) + ) + + assert "wholly_different" not in stripped + assert stripped == _prompt() 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" },