This is an automated email from the ASF dual-hosted git repository.
wenjin272 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
The following commit(s) were added to refs/heads/main by this push:
new a33f4f2b [docs][examples] Clarify prompt brace handling and use single
braces in JSON examples (#810)
a33f4f2b is described below
commit a33f4f2b05e8a61dafd018cfbe2d1c85b99b523a
Author: Wenjin Xie <[email protected]>
AuthorDate: Mon Jun 8 17:55:16 2026 +0800
[docs][examples] Clarify prompt brace handling and use single braces in
JSON examples (#810)
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) <[email protected]>
---
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 403df4b5..6bf9e77b 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 a6054fa3..7b81f58d 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 3bd463f9..17b5ea9d 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 @@ review_analysis_system_prompt_str = """
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 @@ 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}
