From 998035dcd9dfe384f5f17607b5680337d8d7faa4 Mon Sep 17 00:00:00 2001 From: WenjinXie Date: Mon, 8 Jun 2026 16:52:27 +0800 Subject: [PATCH] [docs][examples] Clarify prompt brace handling and use single braces in JSON examples SafeFormatter (Python) and Prompt.formatMessages (Java) only substitute {key}; they do not collapse {{ }} to { }. Doubled braces reach the LLM verbatim, which may copy them into replies and break downstream json.loads. - Document the actual brace rules; drop the wrong "double to escape" note. - Switch all JSON examples in docs and the quickstart example to single braces. Cross-reference from yaml.md. Closes #781 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/content/docs/development/prompts.md | 38 ++++++++++++------- docs/content/docs/development/yaml.md | 2 + .../agents/custom_types_and_resources.py | 16 ++++---- 3 files changed, 34 insertions(+), 22 deletions(-) diff --git a/docs/content/docs/development/prompts.md b/docs/content/docs/development/prompts.md index 403df4b59..6bf9e77bb 100644 --- a/docs/content/docs/development/prompts.md +++ b/docs/content/docs/development/prompts.md @@ -55,20 +55,20 @@ product_suggestion_prompt_str = """ Based on the rating distribution and user dissatisfaction reasons, generate three actionable suggestions for product improvement. Input format: -{{ +{ "id": "1", "score_histogram": ["10%", "20%", "10%", "15%", "45%"], "unsatisfied_reasons": ["reason1", "reason2", "reason3"] -}} +} Ensure that your response can be parsed by Python json, use the following format as an example: -{{ +{ "suggestion_list": [ "suggestion1", "suggestion2", "suggestion3" ] -}} +} input: {input} @@ -109,7 +109,7 @@ Prompt productSuggestionPrompt = Prompt.fromText(PRODUCT_SUGGESTION_PROMPT_STR); **Key points:** - Use `{variable_name}` for template variables that will be substituted at runtime -- Escape literal braces by doubling them: `{{` and `}}` +- `{variable_name}` is the only substitution syntax. Any `{` or `}` that is not part of a known placeholder passes through verbatim, so JSON examples inside a prompt should use single braces. There is no `{{` / `}}` escape — doubled braces are emitted to the LLM as literal `{{` and `}}`, which the model may copy into its reply and break downstream `json.loads` ### Creating from Messages @@ -128,17 +128,17 @@ review_analysis_prompt = Prompt.from_messages( satisfaction score (1-5) and potential reasons for dissatisfaction. Example input format: - {{ + { "id": "12345", "review": "The headphones broke after one week of use." - }} + } Ensure your response can be parsed by Python JSON: - {{ + { "id": "12345", "score": 1, "reasons": ["poor quality"] - }} + } """, ), ChatMessage( @@ -208,17 +208,17 @@ class ReviewAnalysisAgent(Agent): satisfaction score (1-5) and potential reasons for dissatisfaction. Example input format: - {{ + { "id": "12345", "review": "The headphones broke after one week of use." - }} + } Ensure your response can be parsed by Python JSON: - {{ + { "id": "12345", "score": 1, "reasons": ["poor quality"] - }} + } """, ), ChatMessage( @@ -335,4 +335,14 @@ public class ReviewAnalysisAgent extends Agent { {{< /tabs >}} -Prompts use `{variable_name}` syntax for template variables. Variables are filled from the `prompt_args` argument of `ChatRequestEvent` (Python) / the `promptArgs` constructor argument (Java). The prompt is automatically applied when the chat model is invoked. \ No newline at end of file +Prompts use `{variable_name}` syntax for template variables. Variables are filled from the `prompt_args` argument of `ChatRequestEvent` (Python) / the `promptArgs` constructor argument (Java). The prompt is automatically applied when the chat model is invoked. + +## Brace Handling + +`{variable_name}` is the only template syntax. When a prompt is rendered: + +- `{name}` is replaced with the matching argument; if no argument is supplied, the placeholder is left unchanged. +- Any other `{` or `}` (including JSON braces in examples) passes through verbatim. +- There is **no** `{{` / `}}` escape. Unlike Python f-strings and `str.format`, doubled braces are *not* collapsed to single braces — they reach the LLM as literal `{{` and `}}`. + +Write literal JSON examples with single braces. Doubling them sends `{{` / `}}` to the model, which may copy that form into its reply and break downstream `json.loads`. \ No newline at end of file diff --git a/docs/content/docs/development/yaml.md b/docs/content/docs/development/yaml.md index 30760d803..1a3378821 100644 --- a/docs/content/docs/development/yaml.md +++ b/docs/content/docs/development/yaml.md @@ -127,6 +127,8 @@ prompts: text: "this is the {value}" ``` +`{variable_name}` is the only substitution syntax, and there is no `{{` / `}}` escape — write JSON examples in prompt `content` with single braces. See [Brace Handling]({{< ref "docs/development/prompts#brace-handling" >}}). + **Tool** — points at a callable that the chat model can invoke. | Field | Required | Description | diff --git a/python/flink_agents/examples/quickstart/agents/custom_types_and_resources.py b/python/flink_agents/examples/quickstart/agents/custom_types_and_resources.py index 3bd463f97..17b5ea9db 100644 --- a/python/flink_agents/examples/quickstart/agents/custom_types_and_resources.py +++ b/python/flink_agents/examples/quickstart/agents/custom_types_and_resources.py @@ -29,19 +29,19 @@ satisfaction score (1-5) and potential reasons for dissatisfaction. Example input format: - {{ + { "id": "12345", "review": "The headphones broke after one week of use. Very poor quality." - }} + } Ensure your response can be parsed by Python JSON, using this format as an example: - {{ + { "id": "12345", "score": 1, "reasons": [ "poor quality" ] - }} + } Please note that if a product review includes dissatisfaction with the shipping process, you should first notify the shipping manager using the appropriate tools. After executing @@ -92,20 +92,20 @@ Based on the rating distribution and user dissatisfaction reasons, generate three actionable suggestions for product improvement. Input format: - {{ + { "id": "1", "score_histogram": ["10%", "20%", "10%", "15%", "45%"], "unsatisfied_reasons": ["reason1", "reason2", "reason3"] - }} + } Ensure that your response can be parsed by Python json,use the following format as an example: - {{ + { "suggestion_list": [ "suggestion1", "suggestion2", "suggestion3" ] - }} + } input: {input}