|
1 | | -Prompts are the inputs or queries that a user or a program gives to a Large Learning Model ([LLM](https://en.wikipedia.org/wiki/Wikipedia:Large_language_models)) AI, |
2 | | -in order to elicit a specific response from the model. |
3 | | - |
4 | | -Prompts can be natural |
5 | | -language sentences or questions, or code snippets or commands, or any combination |
6 | | -of text or code, depending on the domain and the task. |
7 | | - |
8 | | -Prompts can also be nested |
9 | | -or chained, meaning that the output of one prompt can be used as the input of another |
10 | | -prompt, creating more complex and dynamic interactions with the model. |
11 | | - |
12 | 1 | # SK Prompt Template Syntax |
13 | 2 |
|
14 | | -The Semantic Kernel prompt template language is a simple and powerful way to |
15 | | -define and compose AI |
16 | | -[functions](GLOSSARY.md) |
17 | | -**using plain text**. |
18 | | -You can use it to create natural language prompts, generate responses, extract |
19 | | -information, **invoke other prompts** or perform any other task that can be |
20 | | -expressed with text. |
21 | | - |
22 | | -The language supports three basic features that allow you to (**#1**) include |
23 | | -variables, (**#2**) call external functions, and (**#3**) pass parameters to functions. |
24 | | - |
25 | | -It is not required to write any code or import any external libraries, just use the |
26 | | -curly braces `{{...}}` to embed expressions in your prompts. |
27 | | -Semantic Kernel will parse your template and execute the logic behind it. |
28 | | -This way, you can easily integrate AI into your apps with minimal effort and |
29 | | -maximum flexibility. |
30 | | - |
31 | | -## Variables |
32 | | - |
33 | | -To include a variable value in your text, use the `{{$variableName}}` syntax. |
34 | | -For example, if you have a variable called `name` that holds the user's name, |
35 | | -you can write: |
36 | | - |
37 | | - Hello {{$name}}, welcome to Semantic Kernel! |
38 | | - |
39 | | -This will produce a greeting with the user's name. |
40 | | - |
41 | | -Spaces are ignored, so if you find it more readable, you can also write: |
42 | | - |
43 | | - Hello {{ $name }}, welcome to Semantic Kernel! |
44 | | - |
45 | | -## Function calls |
46 | | - |
47 | | -To call an external function and embed the result in your text, use the |
48 | | -`{{namespace.functionName}}` syntax. |
49 | | -For example, if you have a function called `weather.getForecast` that returns |
50 | | -the weather forecast for a given location, you can write: |
51 | | - |
52 | | - The weather today is {{weather.getForecast}}. |
53 | | - |
54 | | -This will produce a sentence with the weather forecast for the default location |
55 | | -stored in the `input` variable. |
56 | | -The `input` variable is set automatically by the kernel when invoking a function. |
57 | | -For instance, the code above is equivalent to: |
58 | | - |
59 | | - The weather today is {{weather.getForecast $input}}. |
60 | | - |
61 | | -## Function parameters |
62 | | - |
63 | | -To call an external function and pass a parameter to it, use the |
64 | | -`{{namespace.functionName $varName}}` and |
65 | | -`{{namespace.functionName "value"}}` syntax. |
66 | | -For example, if you want to pass a different input to the weather forecast |
67 | | -function, you can write: |
68 | | - |
69 | | - The weather today in {{$city}} is {{weather.getForecast $city}}. |
70 | | - The weather today in Schio is {{weather.getForecast "Schio"}}. |
71 | | - |
72 | | -This will produce two sentences with the weather forecast for two different |
73 | | -locations, using the city stored in the _`city`_ **variable** and the _"Schio"_ |
74 | | -location **value** hardcoded in the prompt template. |
75 | | - |
76 | | -## Design Principles |
77 | | - |
78 | | -The template language is designed to be simple and fast to render, allowing |
79 | | -to create functions with a simple text editor, using natural language, reducing |
80 | | -special syntax to a minimum, and minimizing edge cases. |
81 | | - |
82 | | -The template language uses the **«`$`»** symbol on purpose, to clearly distinguish |
83 | | -between function calls that retrieve content executing some code, from variables, |
84 | | -which are replaced with data from the local temporary memory. |
85 | | - |
86 | | -Branching features such as _"if"_, _"for"_, and code blocks are not part of SK's |
87 | | -template language. This reflects SK's design principle of using natural language |
88 | | -as much as possible, with a clear separation from traditional programming code. |
89 | | - |
90 | | -By using a simple language, the kernel can also avoid complex parsing and |
91 | | -external dependencies, resulting in a fast and memory efficient processing. |
92 | | - |
93 | | -## Semantic function example |
94 | | - |
95 | | -A Semantic Function is a function written in a natural language in a text file (i.e., "skprompt.txt") using SK's Prompt Template language. The following is a simple example of a semantic function defined with a prompt template, using the syntax described. |
96 | | - |
97 | | -`== File: skprompt.txt ==` |
98 | | - |
99 | | -``` |
100 | | -My name: {{msgraph.GetMyName}} |
101 | | -My email: {{msgraph.GetMyEmailAddress}} |
102 | | -My hobbies: {{memory.recall "my hobbies"}} |
103 | | -Recipient: {{$recipient}} |
104 | | -Email to reply to: |
105 | | -========= |
106 | | -{{$sourceEmail}} |
107 | | -========= |
108 | | -Generate a response to the email, to say: {{$input}} |
109 | | -
|
110 | | -Include the original email quoted after the response. |
111 | | -``` |
112 | | - |
113 | | -If we were to write that function in C#, it would look something like: |
114 | | - |
115 | | -```csharp |
116 | | -async Task<string> GenResponseToEmailAsync( |
117 | | - string whatToSay, |
118 | | - string recipient, |
119 | | - string sourceEmail) |
120 | | -{ |
121 | | - try { |
122 | | - string name = await this._msgraph.GetMyName(); |
123 | | - } catch { |
124 | | - ... |
125 | | - } |
126 | | - |
127 | | - try { |
128 | | - string email = await this._msgraph.GetMyEmailAddress(); |
129 | | - } catch { |
130 | | - ... |
131 | | - } |
132 | | - |
133 | | - try { |
134 | | - // Use AI to generate an email using the 5 given variables |
135 | | - // Take care of retry logic, tracking AI costs, etc. |
136 | | - string response = await ... |
137 | | - |
138 | | - return response; |
139 | | - } catch { |
140 | | - ... |
141 | | - } |
142 | | -} |
143 | | -``` |
144 | | - |
145 | | -# Notes about special chars |
146 | | - |
147 | | -Semantic function templates are text files, so there is no need to escape special chars |
148 | | -like new lines and tabs. However, there are two cases that require a special syntax: |
149 | | - |
150 | | -1. Including double curly braces in the prompt templates |
151 | | -2. Passing to functions hardcoded values that include quotes |
152 | | - |
153 | | -## Prompts needing double curly braces |
154 | | - |
155 | | -Double curly braces have a special use case, they are used to inject variables, |
156 | | -values, and functions into templates. |
157 | | - |
158 | | -If you need to include the **`{{`** and **`}}`** sequences in your prompts, which |
159 | | -could trigger special rendering logic, the best solution is to use string values |
160 | | -enclosed in quotes, like `{{ "{{" }}` and `{{ "}}" }}` |
161 | | - |
162 | | -For example: |
163 | | - |
164 | | - {{ "{{" }} and {{ "}}" }} are special SK sequences. |
165 | | - |
166 | | -will render to: |
167 | | - |
168 | | - {{ and }} are special SK sequences. |
169 | | - |
170 | | -## Values that include quotes, and escaping |
171 | | - |
172 | | -Values can be enclosed using **single quotes** and **double quotes**. |
173 | | - |
174 | | -To avoid the need for special syntax, when working with a value that contains |
175 | | -_single quotes_, we recommend wrapping the value with _double quotes_. Similarly, |
176 | | -when using a value that contains _double quotes_, wrap the value with _single quotes_. |
177 | | - |
178 | | -For example: |
179 | | - |
180 | | - ...text... {{ functionName "one 'quoted' word" }} ...text... |
181 | | - ...text... {{ functionName 'one "quoted" word' }} ...text... |
182 | | - |
183 | | -For those cases where the value contains both single and double quotes, you will |
184 | | -need _escaping_, using the special **«`\`»** symbol. |
185 | | - |
186 | | -When using double quotes around a value, use **«`\"`»** to include a double quote |
187 | | -symbol inside the value: |
188 | | - |
189 | | - ... {{ "quotes' \"escaping\" example" }} ... |
190 | | - |
191 | | -and similarly, when using single quotes, use **«`\'`»** to include a single quote |
192 | | -inside the value: |
193 | | - |
194 | | - ... {{ 'quotes\' "escaping" example' }} ... |
195 | | - |
196 | | -Both are rendered to: |
197 | | - |
198 | | - ... quotes' "escaping" example ... |
199 | | - |
200 | | -Note that for consistency, the sequences **«`\'`»** and **«`\"`»** do always render |
201 | | -to **«`'`»** and **«`"`»**, even when escaping might not be required. |
202 | | - |
203 | | -For instance: |
204 | | - |
205 | | - ... {{ 'no need to \"escape" ' }} ... |
206 | | - |
207 | | -is equivalent to: |
208 | | - |
209 | | - ... {{ 'no need to "escape" ' }} ... |
210 | | - |
211 | | -and both render to: |
212 | | - |
213 | | - ... no need to "escape" ... |
214 | | - |
215 | | -In case you may need to render a backslash in front of a quote, since **«`\`»** |
216 | | -is a special char, you will need to escape it too, and use the special sequences |
217 | | -**«`\\\'`»** and **«`\\\"`»**. |
218 | | - |
219 | | -For example: |
220 | | - |
221 | | - {{ 'two special chars \\\' here' }} |
222 | | - |
223 | | -is rendered to: |
224 | | - |
225 | | - two special chars \' here |
226 | | - |
227 | | -Similarly to single and double quotes, the symbol **«`\`»** doesn't always need |
228 | | -to be escaped. However, for consistency, it can be escaped even when not required. |
229 | | - |
230 | | -For instance: |
231 | | - |
232 | | - ... {{ 'c:\\documents\\ai' }} ... |
233 | | - |
234 | | -is equivalent to: |
235 | | - |
236 | | - ... {{ 'c:\documents\ai' }} ... |
237 | | - |
238 | | -and both are rendered to: |
239 | | - |
240 | | - ... c:\documents\ai ... |
241 | | - |
242 | | -Lastly, backslashes have a special meaning only when used in front of |
243 | | -**«`'`»**, **«`"`»** and **«`\`»**. |
244 | | - |
245 | | -In all other cases, the backslash character has no impact and is rendered as is. |
246 | | -For example: |
247 | | - |
248 | | - {{ "nothing special about these sequences: \0 \n \t \r \foo" }} |
249 | | - |
250 | | -is rendered to: |
| 3 | +This document has been moved to the Semantic Kernel Documentation site. You can find it by navigating to the [Prompt template syntax](https://learn.microsoft.com/en-us/semantic-kernel/prompt-engineering/prompt-template-syntax) page. |
251 | 4 |
|
252 | | - nothing special about these sequences: \0 \n \t \r \foo |
| 5 | +To make an update on the page, file a PR on the [docs repo.](https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/semantic-kernel/prompt-engineering/prompt-template-syntax.md) |
0 commit comments