@lowdefy/docs-content 6.1.0 → 7.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +7 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/validate.md +7 -4
  31. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  32. package/content/agents/agent-endpoint-tools.md +24 -0
  33. package/content/agents/agent-properties.md +13 -3
  34. package/content/agents/agent-server-hooks.md +1 -1
  35. package/content/agents/agentchat.md +43 -7
  36. package/content/agents/agentconversations.md +42 -8
  37. package/content/agents/agents-introduction.md +107 -0
  38. package/content/callback-reference/auth0logoutcallback.md +54 -0
  39. package/content/concepts/ai-agent-docs.md +455 -106
  40. package/content/concepts/blocks.md +150 -0
  41. package/content/concepts/connections-and-requests.md +402 -0
  42. package/content/concepts/custom-html.md +42 -0
  43. package/content/concepts/custom-styling.md +50 -5
  44. package/content/concepts/dynamic-page-content.md +309 -0
  45. package/content/concepts/events-and-actions.md +154 -2
  46. package/content/concepts/four-primitives.md +31 -0
  47. package/content/concepts/html-attributes.md +293 -0
  48. package/content/concepts/i18n.md +8 -3
  49. package/content/concepts/keyboard-shortcuts.md +2 -2
  50. package/content/concepts/layout-overview.md +1 -1
  51. package/content/concepts/logger.md +99 -0
  52. package/content/concepts/lowdefy-api.md +1319 -0
  53. package/content/concepts/lowdefy-schema.md +136 -3
  54. package/content/concepts/menus.md +8 -7
  55. package/content/concepts/module-authoring.md +76 -5
  56. package/content/concepts/modules.md +3 -1
  57. package/content/concepts/notifications.md +180 -0
  58. package/content/concepts/operators.md +7 -0
  59. package/content/concepts/page-and-app-state.md +252 -0
  60. package/content/concepts/page-paths.md +209 -0
  61. package/content/concepts/theming.md +582 -0
  62. package/content/connections/aigateway.md +375 -0
  63. package/content/connections/anthropic.md +169 -2
  64. package/content/connections/awss3.md +178 -2
  65. package/content/connections/axioshttp.md +181 -0
  66. package/content/connections/google.md +169 -2
  67. package/content/connections/mongodb.md +1014 -3
  68. package/content/connections/openai-connection.md +169 -2
  69. package/content/connections/sendgridmail.md +2 -0
  70. package/content/connections/smtp.md +3 -1
  71. package/content/connections/treg.md +329 -0
  72. package/content/container-blocks/affix.md +47 -7
  73. package/content/container-blocks/alert.md +76 -24
  74. package/content/container-blocks/badge.md +100 -24
  75. package/content/container-blocks/box.md +9 -9
  76. package/content/container-blocks/card.md +132 -27
  77. package/content/container-blocks/carousel.md +60 -7
  78. package/content/container-blocks/collapse.md +153 -9
  79. package/content/container-blocks/configprovider.md +35 -13
  80. package/content/container-blocks/confirmmodal.md +69 -23
  81. package/content/container-blocks/content.md +62 -98
  82. package/content/container-blocks/descriptions.md +45 -4
  83. package/content/container-blocks/drawer.md +139 -28
  84. package/content/container-blocks/dropdownmenu.md +119 -31
  85. package/content/container-blocks/flex.md +40 -62
  86. package/content/container-blocks/footer.md +15 -11
  87. package/content/container-blocks/googlemapsheatmap.md +1 -1
  88. package/content/container-blocks/googlemapsscript.md +2 -2
  89. package/content/container-blocks/header.md +71 -36
  90. package/content/container-blocks/label.md +34 -7
  91. package/content/container-blocks/layout.md +52 -34
  92. package/content/container-blocks/masonry.md +17 -71
  93. package/content/container-blocks/mobilemenu.md +131 -88
  94. package/content/container-blocks/modal.md +161 -26
  95. package/content/container-blocks/pageheadermenu.md +138 -31
  96. package/content/container-blocks/pagesidebarlayout.md +230 -27
  97. package/content/container-blocks/pagesidermenu.md +153 -43
  98. package/content/container-blocks/popover.md +34 -31
  99. package/content/container-blocks/result.md +32 -21
  100. package/content/container-blocks/sider.md +85 -122
  101. package/content/container-blocks/span.md +7 -7
  102. package/content/container-blocks/spinner.md +3 -3
  103. package/content/container-blocks/splitter.md +150 -68
  104. package/content/container-blocks/tabs.md +64 -12
  105. package/content/container-blocks/tooltip.md +22 -46
  106. package/content/container-blocks/watermark.md +22 -4
  107. package/content/controls/parallel_for.md +21 -2
  108. package/content/controls/reject.md +24 -3
  109. package/content/controls/return.md +17 -1
  110. package/content/controls/throw.md +1 -0
  111. package/content/controls/try.md +4 -2
  112. package/content/controls/while.md +46 -0
  113. package/content/deployment/deployment-environments.md +10 -7
  114. package/content/deployment/docker.md +22 -7
  115. package/content/deployment/node-server.md +4 -0
  116. package/content/deployment/vercel.md +17 -6
  117. package/content/display-blocks/aggrid.md +36 -19
  118. package/content/display-blocks/anchor.md +16 -15
  119. package/content/display-blocks/avatar.md +57 -37
  120. package/content/display-blocks/breadcrumb.md +70 -21
  121. package/content/display-blocks/button.md +93 -19
  122. package/content/display-blocks/calendar.md +12 -0
  123. package/content/display-blocks/clickablehtml.md +239 -0
  124. package/content/display-blocks/dangeroushtml.md +1 -1
  125. package/content/display-blocks/difflist.md +1 -1
  126. package/content/display-blocks/difftimeline.md +1 -1
  127. package/content/display-blocks/divider.md +64 -3
  128. package/content/display-blocks/dropdownbutton.md +81 -30
  129. package/content/display-blocks/echart.md +35 -1
  130. package/content/display-blocks/eventlog.md +363 -0
  131. package/content/display-blocks/floatbutton.md +129 -42
  132. package/content/display-blocks/html.md +61 -1
  133. package/content/display-blocks/icon.md +250 -67
  134. package/content/display-blocks/img.md +2 -2
  135. package/content/display-blocks/menu.md +146 -73
  136. package/content/display-blocks/message.md +38 -124
  137. package/content/display-blocks/notification.md +94 -222
  138. package/content/display-blocks/paragraph.md +59 -9
  139. package/content/display-blocks/pollingtimer.md +263 -0
  140. package/content/display-blocks/progress.md +96 -17
  141. package/content/display-blocks/qrcode.md +19 -4
  142. package/content/display-blocks/s3download.md +1 -1
  143. package/content/display-blocks/search.md +19 -9
  144. package/content/display-blocks/skeletonbutton.md +1 -0
  145. package/content/display-blocks/skeletoninput.md +1 -0
  146. package/content/display-blocks/statistic.md +75 -17
  147. package/content/display-blocks/steps.md +58 -25
  148. package/content/display-blocks/table.md +2527 -0
  149. package/content/display-blocks/tablelight.md +621 -0
  150. package/content/display-blocks/tag.md +102 -17
  151. package/content/display-blocks/title.md +50 -11
  152. package/content/display-blocks/tour.md +33 -23
  153. package/content/input-blocks/autocomplete.md +81 -9
  154. package/content/input-blocks/buttonselector.md +45 -8
  155. package/content/input-blocks/captcha.md +40 -0
  156. package/content/input-blocks/checkboxselector.md +97 -7
  157. package/content/input-blocks/checkboxswitch.md +33 -3
  158. package/content/input-blocks/colorselector.md +63 -14
  159. package/content/input-blocks/daterangeselector.md +165 -45
  160. package/content/input-blocks/dateselector.md +139 -41
  161. package/content/input-blocks/datetimeselector.md +158 -49
  162. package/content/input-blocks/inputgallery.md +3 -3
  163. package/content/input-blocks/intentinput.md +207 -0
  164. package/content/input-blocks/monthselector.md +120 -52
  165. package/content/input-blocks/multipleselector.md +150 -39
  166. package/content/input-blocks/numberinput.md +98 -12
  167. package/content/input-blocks/pagination.md +70 -14
  168. package/content/input-blocks/paragraphinput.md +51 -37
  169. package/content/input-blocks/passwordinput.md +60 -6
  170. package/content/input-blocks/phonenumberinput.md +59 -26
  171. package/content/input-blocks/placesautocomplete.md +319 -0
  172. package/content/input-blocks/radioselector.md +83 -7
  173. package/content/input-blocks/ratingslider.md +57 -26
  174. package/content/input-blocks/s3uploadbutton.md +24 -24
  175. package/content/input-blocks/s3uploaddragger.md +3 -3
  176. package/content/input-blocks/s3uploadphoto.md +5 -5
  177. package/content/input-blocks/segmentedselector.md +72 -32
  178. package/content/input-blocks/selector.md +109 -21
  179. package/content/input-blocks/switch.md +65 -17
  180. package/content/input-blocks/tableinput.md +445 -0
  181. package/content/input-blocks/tagmultipleselector.md +114 -0
  182. package/content/input-blocks/tagselector.md +114 -0
  183. package/content/input-blocks/textarea.md +32 -3
  184. package/content/input-blocks/textinput.md +70 -29
  185. package/content/input-blocks/tiptapinput.md +1 -1
  186. package/content/input-blocks/tiptapmentioninput.md +2 -2
  187. package/content/input-blocks/titleinput.md +39 -12
  188. package/content/input-blocks/treeinput.md +49 -25
  189. package/content/input-blocks/treemultipleselector.md +127 -10
  190. package/content/input-blocks/treeselector.md +97 -9
  191. package/content/input-blocks/upload.md +64 -15
  192. package/content/input-blocks/uploaddragger.md +17 -1
  193. package/content/input-blocks/uploadphoto.md +18 -1
  194. package/content/input-blocks/weekselector.md +120 -55
  195. package/content/learn/introduction.md +27 -0
  196. package/content/learn/quickstart.md +53 -0
  197. package/content/list-blocks/controlledlist.md +24 -15
  198. package/content/list-blocks/list.md +11 -11
  199. package/content/list-blocks/masonrylist.md +7 -34
  200. package/content/migration/auth-upgrade.md +337 -0
  201. package/content/migration/upgrade-guide.md +1 -0
  202. package/content/migration/v3-to-v4.md +417 -0
  203. package/content/migration/v6-to-v7.md +620 -0
  204. package/content/operators/_agent.md +155 -0
  205. package/content/operators/_app.md +2 -1
  206. package/content/operators/_array.md +122 -1
  207. package/content/operators/_build.md +1 -0
  208. package/content/operators/_credential.md +57 -0
  209. package/content/operators/_cron.md +292 -0
  210. package/content/operators/_date.md +2 -0
  211. package/content/operators/_error.md +24 -1
  212. package/content/operators/_get.md +6 -6
  213. package/content/operators/_hmac.md +78 -0
  214. package/content/operators/_js.md +2 -1
  215. package/content/operators/_location.md +1 -1
  216. package/content/operators/_media.md +13 -0
  217. package/content/operators/_module.md +56 -2
  218. package/content/operators/_operator.md +17 -3
  219. package/content/operators/_path_params.md +82 -0
  220. package/content/operators/_ref.md +258 -0
  221. package/content/operators/_request.md +1 -1
  222. package/content/operators/_request_details.md +6 -0
  223. package/content/operators/_type.md +14 -3
  224. package/content/operators/_url_query.md +2 -0
  225. package/content/operators/_user.md +3 -3
  226. package/content/plugins/plugins-actions.md +10 -0
  227. package/content/plugins/plugins-connections.md +25 -0
  228. package/content/plugins/plugins-dev.md +66 -0
  229. package/content/plugins/plugins-icon-sets.md +267 -0
  230. package/content/plugins/plugins-introduction.md +27 -1
  231. package/content/plugins/plugins.md +19 -0
  232. package/content/plugins/posthog.md +359 -0
  233. package/content/provider-reference/auth-js-providers.md +107 -0
  234. package/content/provider-reference/openidconnectprovider.md +44 -0
  235. package/content/recipes/recipes.md +16 -0
  236. package/content/reference/actions-reference.md +31 -0
  237. package/content/reference/blocks-reference.md +35 -0
  238. package/content/reference/cli.md +403 -0
  239. package/content/reference/connections-reference.md +23 -0
  240. package/content/reference/operators-reference.md +47 -0
  241. package/content/reference/reference.md +16 -0
  242. package/content/reference/schema-reference.md +12 -0
  243. package/content/testing/config-tests.md +677 -0
  244. package/content/testing/e2e-configuration.md +31 -1
  245. package/content/testing/e2e-getting-started.md +1 -1
  246. package/content/testing/e2e-introduction.md +1 -1
  247. package/content/testing/e2e-writing-tests.md +12 -1
  248. package/content/testing/explore-pull-request.md +136 -0
  249. package/content/testing/journey-data-sets.md +326 -0
  250. package/content/tutorial/tutorial-actions-operators.md +2 -2
  251. package/content/tutorial/tutorial-add-blocks.md +2 -2
  252. package/content/tutorial/tutorial-create-page.md +48 -2
  253. package/content/tutorial/tutorial-display-data-page.md +3 -3
  254. package/content/tutorial/tutorial-requests-api.md +155 -0
  255. package/content/tutorial/tutorial-requests-sql.md +153 -0
  256. package/content/tutorial/tutorial-start.md +66 -1
  257. package/content/user-authentication/auth-configuration.md +267 -0
  258. package/content/user-authentication/auth-providers.md +24 -0
  259. package/content/user-authentication/auth-steps.md +141 -0
  260. package/content/user-authentication/login-and-logout.md +160 -8
  261. package/content/user-authentication/mcp-oauth.md +424 -0
  262. package/content/user-authentication/organizations.md +246 -0
  263. package/content/user-authentication/protected-pages-apis.md +97 -0
  264. package/content/user-authentication/roles.md +49 -0
  265. package/content/user-authentication/two-factor.md +229 -0
  266. package/content/user-authentication/user-object.md +58 -0
  267. package/content/user-authentication/users-introduction.md +8 -0
  268. package/content/websockets/websocket-publish.md +105 -0
  269. package/content/websockets/websocket-subscriptions.md +136 -0
  270. package/content/websockets/websockets-introduction.md +101 -0
  271. package/hazards.json +44 -0
  272. package/index.json +3691 -14
  273. package/package.json +11 -1
  274. package/scripts/collectImportedFiles.js +80 -0
  275. package/scripts/extractAgentDocs.js +41 -30
  276. package/scripts/hashDocSources.js +38 -0
  277. package/scripts/isRedirectPage.js +26 -0
  278. package/scripts/recordSourceHashes.js +100 -0
  279. package/scripts/resolvePageSections.js +42 -0
  280. package/scripts/sectionKind.js +27 -0
  281. package/content/concepts/cli.md +0 -223
  282. package/content/other/introduction.md +0 -39
  283. package/content/other/next-auth-providers.md +0 -3
  284. /package/content/{other → actions}/updatesession.md +0 -0
@@ -0,0 +1,46 @@
1
+ # MongoDBAuthAdapter
2
+
3
+ The MongoDBAuthAdapter stores the auth engine's users, sessions, accounts, organizations and related records in a MongoDB database. It is configured as `auth.database` and ships with the `MongoDBCollection` connection package.
4
+
5
+ Collection names follow the fixed `user-*` naming convention applied by the auth engine (`users`, `user-sessions`, `user-accounts`, ...) — there is no collection rename configuration. The `attributes` fields on users, members and invitations are stored as native sub-documents, so they can be filtered and aggregated with normal MongoDB queries.
6
+
7
+ If you are upgrading from the old `MongoDBAdapter`: the type is renamed, `databaseUri` becomes `uri`, and `options.databaseName` folds into the URI path or the `database` property. See the [auth upgrade guide](/auth-upgrade).
8
+
9
+ #### Properties
10
+
11
+ ###### object
12
+ - `uri: string`: Required - Connection uri string for the MongoDB deployment. Should be stored using the _secret operator.
13
+ - `database: string`: Set the MongoDB database name. This is optional if the database name is specified in the `uri`.
14
+ - `mongoDBClientOptions: object`: See the [driver documentation](https://mongodb.github.io/node-mongodb-native/) for more information.
15
+
16
+ #### Examples
17
+
18
+ ###### Minimum configuration.
19
+
20
+ ```yaml
21
+ lowdefy: 7.0.0
22
+ auth:
23
+ database:
24
+ id: auth_db
25
+ type: MongoDBAuthAdapter
26
+ properties:
27
+ uri:
28
+ _secret: AUTH_DATABASE_URI
29
+ ```
30
+
31
+ ###### Full configuration.
32
+
33
+ ```yaml
34
+ lowdefy: 7.0.0
35
+ auth:
36
+ database:
37
+ id: auth_db
38
+ type: MongoDBAuthAdapter
39
+ properties:
40
+ uri:
41
+ _secret: AUTH_DATABASE_URI
42
+ database: my-database # Optional
43
+ # Optional MongoDB client options, only set these if necessary
44
+ mongoDBClientOptions:
45
+ connectTimeoutMS: 2000
46
+ ```
@@ -162,6 +162,30 @@ agents:
162
162
  confirm: true
163
163
  ```
164
164
 
165
+ ## Knowing the Calling Agent
166
+
167
+ A tool endpoint can read which agent called it with the [`_agent`](/_agent) operator: `_agent: id` is the agent's `id`, `_agent: conversationId` the chat's conversation id. Lowdefy sets both from the running agent, so the model cannot set or hide them through the tool's input. Endpoints the tool endpoint calls in turn see the same agent. On a call that did not come from an agent, `_agent` returns `null`.
168
+
169
+ ```yaml
170
+ api:
171
+ - id: create-support-ticket
172
+ type: Api
173
+ # ...
174
+ routine:
175
+ - id: insert
176
+ type: MongoDBInsertOne
177
+ connectionId: tickets_db
178
+ properties:
179
+ doc:
180
+ subject:
181
+ _payload: subject
182
+ createdBy:
183
+ userId:
184
+ _user: id
185
+ agentId:
186
+ _agent: id
187
+ ```
188
+
165
189
  ## Reserved Tool Names
166
190
 
167
191
  Lowdefy registers a small set of platform tools automatically (for example, `update-page-state`, which the [`AgentChat`](/AgentChat#shared-state) block wires up when `sharedState` is set). The following tool names are reserved and cannot be used as endpoint ids or sub-agent ids — the build will fail if one is encountered:
@@ -6,7 +6,7 @@ Agent properties configure the model and its behavior. They are set in the `prop
6
6
 
7
7
  - `model: string`: __Required__ - The model identifier (e.g. `claude-sonnet-4-20250514`, `gpt-4o`, `gemini-2.5-pro`).
8
8
  - `instructions: string`: System instructions that guide the agent's behavior. This is the system prompt sent to the model with every request. The string passes through the operator parser at request time, so `_t:` works for locale-aware prompts (see [i18n](/i18n)). Note: tool descriptions stay English — translating them can degrade tool-call accuracy on English-trained models.
9
- - `pageContext: boolean`: Default: `false` - When `true`, prepend context about the current page, user, conversation, URL query, and shared state to the instructions. URL query and shared state are only included when the [`AgentChat`](/AgentChat) block sends them as `urlQuery` and `sharedState`. Useful when the agent needs to know who it's talking to or what the user has typed into form fields.
9
+ - `pageContext: boolean`: Default: `false` - When `true`, prepend context about the current page, user, conversation, URL query, path parameters and shared state to the instructions. URL query and shared state are only included when the [`AgentChat`](/AgentChat) block sends them as `urlQuery` and `sharedState`. Path parameters, the values of the placeholders in the page's [`path`](/page-paths), are sent by the block on a page with a path, and included when there are any. Useful when the agent needs to know who it's talking to or what the user has typed into form fields.
10
10
  - `generateTitle: boolean`: Default: `false` - When `true`, generate a short title from the first user message on the first turn of a conversation. Emits a `data-chat-title` data part that fires the [`AgentChat`](/AgentChat) block's `onTitleGenerated` event. Runs concurrently with the response and is non-fatal — a failed title generation logs a warning and does not break the turn.
11
11
 
12
12
  ###### Instructions with user context:
@@ -22,7 +22,7 @@ properties:
22
22
 
23
23
  ## Generation Settings
24
24
 
25
- - `maxOutputTokens: integer`: Maximum tokens the model can generate per step.
25
+ - `maxOutputTokens: integer`: Maximum tokens the model can generate per step. Defaults to the connection's `maxOutputTokens`.
26
26
  - `temperature: number`: Sampling temperature between `0` and `2`. Lower values are more deterministic, higher values more creative. Default depends on the provider.
27
27
  - `topP: number`: Nucleus sampling probability between `0` and `1`. Alternative to temperature — use one or the other.
28
28
  - `topK: integer`: Only sample from the top K token options (not supported by all providers).
@@ -156,13 +156,23 @@ properties:
156
156
  ## Timeouts and Retries
157
157
 
158
158
  - `maxRetries: integer`: Default: `2` - Maximum retries on provider errors. Set to `0` to disable.
159
- - `timeout: number | object`: Timeout configuration.
159
+ - `timeout: number | object`: Timeout configuration. Defaults to the connection's `timeout`.
160
160
  - As a number: total timeout in milliseconds.
161
161
  - As an object with granular control:
162
162
  - `totalMs: number`: Total timeout across all steps.
163
163
  - `stepMs: number`: Timeout per step.
164
164
  - `chunkMs: number`: Timeout between stream chunks.
165
165
 
166
+ A chat turn keeps running when the client disconnects, so its `onFinish` hooks still save the whole conversation; `timeout` and `maxSteps` are what bound it. A `CallAgent` step is cancelled with the routine that runs it: when its request closes or the server's request timeout (`config.requestTimeout`) answers first.
167
+
168
+ ## File Downloads
169
+
170
+ A file in a chat or a `CallAgent` step goes to the model as a link when the provider takes that media type as a link (the main providers do for images and PDFs). Any other file is downloaded by the server and sent as content. The server downloads only an `https:` link to a public address, checking the address on every redirect, and a failed download names the file's host, never its link.
171
+
172
+ - `fileDownload: object`: Limits on a file the server downloads.
173
+ - `maxBytes: integer`: Default: `20971520` (20 MB) - Largest file the server downloads. A larger file fails the turn.
174
+ - `timeout: integer`: Default: `30000` - Milliseconds a file download may take.
175
+
166
176
  ## Provider-Specific Properties
167
177
 
168
178
  - `providerOptions: object`: Pass provider-specific options directly to the AI SDK. Use this for options not covered by the properties above.
@@ -57,7 +57,7 @@ The hook endpoint receives the full turn in `_payload`:
57
57
  | `finishReason` | string | Why the agent stopped (e.g. `'stop'`, `'tool-calls'`, `'length'`). |
58
58
  | `isAborted` | boolean | `true` if the client cancelled the request. |
59
59
  | `usage` | object | Token usage for the turn: `inputTokens`, `outputTokens`, `totalTokens`, `reasoningTokens`, `cacheReadTokens`, `cacheWriteTokens`. |
60
- | `pageId`, `agentId`, `conversationId`, `userId`, `urlQuery`, `sharedState` | | Context values mirrored from the request, **at the top level** of the payload. |
60
+ | `pageId`, `agentId`, `conversationId`, `userId`, `urlQuery`, `pathParams`, `sharedState` | | Context values mirrored from the request, **at the top level** of the payload. |
61
61
 
62
62
  Read these fields at the **top level** of `_payload` (e.g. `_payload: conversationId`, `_payload: usage`) — they are not nested under an `agentContext` key.
63
63
 
@@ -66,11 +66,12 @@ The `AgentChat` block renders a streaming AI chat interface. It connects to a [L
66
66
  | Property | Type | Default | Description |
67
67
  | --- | --- | --- | --- |
68
68
  | `agentId` | string | | __Required__ - The `id` of the agent to connect to. |
69
- | `conversationId` | string | | Active conversation ID. When this changes, any in-flight reply is aborted (so it stops emitting `onDataPart` and tool events into the page) and messages are cleared. If left empty, the block auto-mints a stable id for the session and surfaces it via `onConversationStart`, so every turn posts a consistent id. App-supplied ids are always authoritative. |
70
- | `messages` | array | | Load messages externally. `undefined` = no sync, `null` = clear, array = load. Re-synced whenever the array's length, last message id or `conversationId` changes. |
71
- | `loading` | boolean | `false` | The app is still loading this conversation's transcript (for example, reading it from a database after a conversation switch). While `true`, a skeleton replaces the message area, suggestions are hidden and the composer is disabled, so nothing can be sent into a conversation whose messages have not synced yet. Drive it from state alongside `messages`, for the window before the transcript has synced — not while a reply is streaming, since a disabled composer also hides the stop control. |
72
- | `urlQuery` | object | | Query parameters sent with each request. Available server-side via `_payload`. |
69
+ | `conversationId` | string | | Active conversation ID. When this changes, messages are cleared. If left empty, the block auto-mints a stable id for the session and surfaces it via `onConversationStart`, so every turn posts a consistent id. App-supplied ids are always authoritative. |
70
+ | `messages` | array | | Load messages externally. `undefined` = no sync, `null` = clear, array = load. |
71
+ | `feedbackValues` | object | | Ratings already recorded for messages in this conversation, keyed by message id, each `like` or `dislike`. The block does not persist a rating, so without this a reload or a conversation switch shows every message unrated even where your app stored it. A rating clicked this visit takes precedence, so the thumb still responds immediately and a rating the user has just withdrawn is not re-lit by a stale value. |
72
+ | `urlQuery` | object | | Query parameters sent with each request. Available server-side via `_payload`. The page's path parameters (see [Page paths](/page-paths)) are sent as `pathParams` without being set here. |
73
73
  | `sharedState` | object | | Two-way bridge between page state and the agent. See [Shared State](#shared-state). |
74
+ | `sharedStateReadOnly` | boolean | `false` | Send `sharedState` as read-only context: the agent gets no `update-page-state` tool. See [Read-only shared state](#read-only-shared-state). |
74
75
  | `height` | string | `'calc(100dvh - 170px)'` | CSS height of the chat container. Only applies when `display` is `'inline'`. |
75
76
  | `maxWidth` | number | `800` | Maximum width in pixels. |
76
77
  | `display` | string | `'inline'` | `'inline'` renders directly on the page. `'drawer'` renders in a slide-out drawer. |
@@ -195,6 +196,8 @@ Customize message appearance by role:
195
196
  - `avatar: string`: Avatar image URL.
196
197
  - `variant: string`: `'filled'`, `'outlined'`, `'shadow'`, or `'borderless'`.
197
198
  - `shape: string`: `'default'`, `'round'`, or `'corner'`.
199
+ - `styles: object`: Inline styles per bubble part — `root`, `content`, `body`, `header`, `footer`, `avatar`, `extra`. This is how to recolour a bubble: the `filled` background and the `outlined` border come from the theme's `colorPrimary`, and a page stylesheet cannot override them.
200
+ - `classNames: object`: Class names per bubble part, same keys as `styles`.
198
201
  - `user: object`: Same properties as `assistant`.
199
202
 
200
203
  ```yaml
@@ -216,6 +219,8 @@ messageDisplay:
216
219
  - `placeholder: string`: Default: `'Type a message...'` — Input placeholder. When `config.i18n` is configured, falls back to the localized `agent.sender.placeholder` builtin key. See the [i18n concept page](/i18n) for the full list of localizable agent UI keys (tool approval buttons, message actions, tool-result captions, etc.).
217
220
  - `submitType: string`: Default: `'enter'` - Submit key. `'enter'` or `'shiftEnter'`.
218
221
  - `allowSpeech: boolean`: Default: `false` - Enable speech input.
222
+ - `styles: object`: Inline styles per composer part — `root`, `prefix`, `input`, `suffix`, `footer`, `switch`, `content`. This is how to recolour the composer border, which the theme sets and a page stylesheet cannot override.
223
+ - `classNames: object`: Class names per composer part, same keys as `styles`.
219
224
 
220
225
  #### File Attachments
221
226
 
@@ -238,6 +243,8 @@ sender:
238
243
  downloadPolicyRequestId: get_download_url
239
244
  ```
240
245
 
246
+ A file uploaded to storage becomes a file part of the message, `{ type: 'file', url, mediaType, filename, providerMetadata: { lowdefy: { key } } }`, where `key` is the file's storage key from the upload policy. The key sits under `providerMetadata` because the AI SDK keeps no other extra field on a file part, so it survives the saved conversation, the `onFinish` hook's messages and a reload. It is not sent to the model. Use it to sign a fresh link when a saved conversation is reopened (a signed link expires), and read it in a tool endpoint with [`_agent: files`](/_agent). Before each file, the model gets a line naming it (`Attached file: screenshot.png`), so it can pass the name to a tool; the saved messages do not hold that line.
247
+
241
248
  #### Sender Switches
242
249
 
243
250
  Toggle switches in the sender footer. The switch state is included in the `onBeforeSend` event and in message metadata.
@@ -253,7 +260,7 @@ sender:
253
260
  switches:
254
261
  - key: deep_research
255
262
  label: Deep Research
256
- icon: AiOutlineSearch
263
+ icon: search
257
264
  default: false
258
265
  - key: use_knowledge_base
259
266
  label: Use Knowledge Base
@@ -315,6 +322,24 @@ When the agent calls `update-page-state`, the block routes the write through a s
315
322
 
316
323
  With the curated form above, the agent can read `legal_name` and `registration_number`, and calling `update-page-state` with either key writes straight back into the page state — no custom endpoint or `onToolResult` handler required.
317
324
 
325
+ #### Read-only shared state
326
+
327
+ Set `sharedStateReadOnly: true` to give the agent page context it cannot change. The block still sends `sharedState` with each request (available server-side via `_payload`, and in the agent's context block when the agent has [`pageContext: true`](/agent-properties)), but the server does not register the `update-page-state` tool, so the model is never offered a page-state write. Use it when the values are there to inform the agent (the current time, the record the user is looking at) and some of them are also bound to inputs the agent should not overwrite.
328
+
329
+ ###### Send context without the write tool:
330
+ ```yaml
331
+ - id: chat
332
+ type: AgentChat
333
+ properties:
334
+ agentId: assistant
335
+ sharedStateReadOnly: true
336
+ sharedState:
337
+ now:
338
+ _date: now
339
+ space:
340
+ _state: space
341
+ ```
342
+
318
343
  ## Events
319
344
 
320
345
  | Event | When | Event data |
@@ -327,7 +352,7 @@ With the curated form above, the agent can read `legal_name` and `registration_n
327
352
  | `onToolResult` | A tool returns a result. | `toolName`, `toolCallId`, `output`, `error` |
328
353
  | `onError` | A streaming error occurs. | `message` |
329
354
  | `onStop` | User stops generation. | `messages` |
330
- | `onFeedback` | User clicks thumbs up/down. | `messageId`, `messageContent`, `rating` |
355
+ | `onFeedback` | User clicks thumbs up/down. `rating` is `like` or `dislike`, or `default` when the user clicks the selected thumb again to clear the rating — branch on it explicitly rather than treating anything that is not `like` as a dislike. | `messageId`, `messageContent`, `rating` |
331
356
  | `onRegenerate` | User clicks regenerate. | `messageId`, `messages` |
332
357
  | `onDeleteMessage` | User deletes a message. | `messageId`, `content`, `messages` |
333
358
  | `onEditMessage` | User edits and resubmits. | `messageId`, `originalContent`, `newContent`, `messages` |
@@ -335,6 +360,7 @@ With the curated form above, the agent can read `legal_name` and `registration_n
335
360
  | `onSwitchChange` | User toggles a sender switch. | `key`, `checked` |
336
361
  | `onTitleGenerated` | A `data-chat-title` data part arrives — emitted automatically when the agent's [`generateTitle`](/agent-properties) property is set, or manually from an `onFinish` hook. | `title` |
337
362
  | `onDataPart` | Any data part arrives from the server. | `type`, `data`, `id` |
363
+ | `onLinkClick` | User clicks a link in a message. Wiring this event suppresses the default navigation for plain left clicks, so the app can open the target in place; modified clicks (new tab, middle click) always navigate. | `href`, `text` |
338
364
 
339
365
  ###### Validate messages before sending:
340
366
  ```yaml
@@ -366,6 +392,16 @@ events:
366
392
  type: success
367
393
  ```
368
394
 
395
+ Saving is only half of it — the block does not persist a rating, so a
396
+ reload or a conversation switch shows the message unrated again. Pass
397
+ what you stored back through `feedbackValues`, keyed by message id:
398
+
399
+ ```yaml
400
+ properties:
401
+ feedbackValues:
402
+ _request: saved_feedback_for_conversation
403
+ ```
404
+
369
405
  ###### Adapt behavior based on sender switches:
370
406
  ```yaml
371
407
  events:
@@ -433,7 +469,7 @@ Control the chat programmatically using [`CallMethod`](/CallMethod):
433
469
  type: Button
434
470
  properties:
435
471
  title: New Chat
436
- icon: AiOutlinePlus
472
+ icon: add
437
473
  events:
438
474
  onClick:
439
475
  - id: new_id
@@ -25,13 +25,13 @@ The block does not manage data — you load conversations from your database and
25
25
  _state: activeConversationId
26
26
  creation:
27
27
  label: New Chat
28
- icon: AiOutlinePlus
28
+ icon: add
29
29
  menu:
30
30
  - key: rename
31
31
  label: Rename
32
32
  - key: delete
33
33
  label: Delete
34
- icon: AiOutlineDelete
34
+ icon: delete
35
35
  danger: true
36
36
  groupable:
37
37
  collapsible: true
@@ -59,7 +59,7 @@ The block does not manage data — you load conversations from your database and
59
59
  type: Request
60
60
  skip:
61
61
  _ne:
62
- - _event: key
62
+ - _event: action
63
63
  - delete
64
64
  params:
65
65
  - delete_conversation
@@ -74,10 +74,12 @@ The block does not manage data — you load conversations from your database and
74
74
  - `label: string`: Conversation title.
75
75
  - `icon`: Optional icon.
76
76
  - `disabled: boolean`: Whether the item is disabled.
77
+ - `loading: boolean`: Show a spinner in place of the item's icon, for example while a title is being generated.
77
78
  - `timestamp: number`: Timestamp for sorting or display.
78
79
  - `group: string`: Group key (e.g. `'Today'`, `'Yesterday'`, `'Last week'`).
79
80
 
80
81
  - `activeKey: string`: The `key` of the currently selected conversation. Highlights the active item.
82
+ - `loadingKey: string`: The `key` of a conversation that is still loading. That row shows a spinner in place of its icon and is marked `aria-busy`. Set it on select while the transcript is read, and clear it when the read completes (see below).
81
83
  - `width: number`: Default: `250` - Sidebar width in pixels.
82
84
 
83
85
  ### Creation Button
@@ -102,13 +104,45 @@ The block does not manage data — you load conversations from your database and
102
104
  - `label: string`: Label for ungrouped items.
103
105
  - `defaultExpandedKeys: string[]`: Groups expanded by default.
104
106
 
107
+ ###### Mark the selected conversation as loading while its transcript is read:
108
+ ```yaml
109
+ - id: conversations
110
+ type: AgentConversations
111
+ properties:
112
+ items:
113
+ _request: list_conversations
114
+ activeKey:
115
+ _state: activeConversationId
116
+ loadingKey:
117
+ _state: loadingConversationId
118
+ events:
119
+ onSelect:
120
+ - id: switch
121
+ type: SetState
122
+ params:
123
+ activeConversationId:
124
+ _event: key
125
+ loadingConversationId:
126
+ _event: key
127
+ - id: load
128
+ type: Request
129
+ params:
130
+ - load_messages
131
+ - id: loaded
132
+ type: SetState
133
+ params:
134
+ loadingConversationId: null
135
+ ```
136
+
137
+ Pair it with the [`AgentChat`](/AgentChat) `loading` property, driven from the same state, so the chat column shows a skeleton and disables the composer for the same window.
138
+
105
139
  ## Events
106
140
 
107
141
  | Event | When | Event data |
108
142
  | --- | --- | --- |
109
- | `onSelect` | User clicks a conversation. | `key` |
143
+ | `onSelect` | User clicks a conversation. | `key`, `previousKey` |
110
144
  | `onNew` | User clicks the creation button. | |
111
- | `onMenuClick` | User clicks a context menu item. | `key` (menu action), `item` (conversation) |
145
+ | `onMenuClick` | User clicks a context menu item. | `action` (menu item key), `conversationKey`, `conversation` |
112
146
 
113
147
  ###### Handle menu actions:
114
148
  ```yaml
@@ -118,7 +152,7 @@ events:
118
152
  type: CallMethod
119
153
  skip:
120
154
  _ne:
121
- - _event: key
155
+ - _event: action
122
156
  - rename
123
157
  params:
124
158
  blockId: rename_modal
@@ -129,7 +163,7 @@ events:
129
163
  type: Request
130
164
  skip:
131
165
  _ne:
132
- - _event: key
166
+ - _event: action
133
167
  - delete
134
168
  params:
135
169
  - delete_conversation
@@ -137,7 +171,7 @@ events:
137
171
  type: Request
138
172
  skip:
139
173
  _ne:
140
- - _event: key
174
+ - _event: action
141
175
  - delete
142
176
  params:
143
177
  - list_conversations
@@ -0,0 +1,107 @@
1
+ # Agents
2
+
3
+ Lowdefy agents add AI chat capabilities to your app. An agent connects to an AI model provider (like Anthropic, OpenAI, or Google), can use tools to interact with your app's APIs, and streams responses to an [`AgentChat`](/AgentChat) block in the browser.
4
+
5
+ Agents are defined at the root of your Lowdefy configuration, alongside `connections` and `pages`. You define the agent in YAML, and Lowdefy handles the streaming, tool execution, and UI.
6
+
7
+ ## Quick Start
8
+
9
+ A connection, an agent, and a chat block — that's all you need:
10
+
11
+ ```yaml
12
+ lowdefy: 7.0.0
13
+
14
+ connections:
15
+ - id: anthropic
16
+ type: Anthropic
17
+ properties:
18
+ apiKey:
19
+ _secret: ANTHROPIC_API_KEY
20
+
21
+ agents:
22
+ - id: assistant
23
+ type: ClaudeAgent
24
+ connectionId: anthropic
25
+ properties:
26
+ model: claude-sonnet-4-20250514
27
+ instructions: |
28
+ You are a helpful assistant for Acme Corp. Answer questions
29
+ about our products and services. Be friendly and concise.
30
+
31
+ pages:
32
+ - id: chat
33
+ type: PageHeaderMenu
34
+ properties:
35
+ title: Chat
36
+ blocks:
37
+ - id: chat
38
+ type: AgentChat
39
+ properties:
40
+ agentId: assistant
41
+ ```
42
+
43
+ Set the `ANTHROPIC_API_KEY` [secret](/secrets) and you have a fully working AI chat — streaming responses, markdown rendering, code highlighting, and editable messages all work out of the box.
44
+
45
+ ## How Agents Work
46
+
47
+ When a user sends a message in an [`AgentChat`](/AgentChat) block:
48
+
49
+ 1. The message is sent to the Lowdefy server via a streaming API endpoint.
50
+ 2. The server loads the agent configuration, creates a connection to the AI provider, and starts a conversation with the model.
51
+ 3. If the agent has tools, the model can call them. Tool calls execute server-side (API endpoints, MCP servers, or sub-agents) and the results are sent back to the model.
52
+ 4. The model's response streams back to the browser in real time, updating the chat UI as tokens arrive.
53
+
54
+ This tool loop continues until the model produces a final text response or reaches the `maxSteps` limit.
55
+
56
+ ## Agent Definition
57
+
58
+ Agents are defined in the top-level `agents` array in your Lowdefy configuration:
59
+
60
+ - `id: string`: __Required__ - A unique identifier for the agent.
61
+ - `type: string`: __Required__ - The agent type. See [Anthropic](/Anthropic), [OpenAI](/OpenAI-connection), and [Google](/Google) for available types.
62
+ - `connectionId: string`: __Required__ - The `id` of the connection to use.
63
+ - `properties: object`: Model, instructions, and behavior settings. See [Agent Properties](/agent-properties). __Operators are evaluated__.
64
+ - `tools: array`: API endpoint tools. See [Endpoint Tools](/agent-endpoint-tools).
65
+ - `mcp: array`: MCP server tools. See [MCP Tools](/agent-mcp-tools).
66
+ - `agents: array`: Sub-agent tools. See [Multi-Agent](/agent-multi-agent).
67
+ - `hooks: object`: Server-side lifecycle hooks. See [Server Hooks](/agent-server-hooks).
68
+
69
+ ###### Agent with tools, sub-agents, and hooks:
70
+ ```yaml
71
+ agents:
72
+ - id: support_agent
73
+ type: ClaudeAgent
74
+ connectionId: anthropic
75
+ properties:
76
+ model: claude-sonnet-4-20250514
77
+ instructions: |
78
+ You are a customer support agent. Help users find products
79
+ and answer questions. Be friendly and concise.
80
+ maxSteps: 5
81
+ tools:
82
+ - search-products
83
+ - endpointId: create-ticket
84
+ confirm: true
85
+ mcp:
86
+ - mcp_knowledge_base
87
+ agents:
88
+ - agentId: billing_agent
89
+ description: Handles billing and payment questions.
90
+ hooks:
91
+ onFinish:
92
+ - save-conversation
93
+ ```
94
+
95
+ ## Beyond Chat
96
+
97
+ Agents can also run headlessly from [API endpoint routines](/api) using the `CallAgent` step — the agent loops through its tools to completion and the result lands in the routine's `_step` results, no chat UI involved. The step can pass images and documents beside its prompt with `files`. See [Running Agents As A Routine Step](/api) for details.
98
+
99
+ ## What's Next
100
+
101
+ - [Agent Properties](/agent-properties) — Configure model, temperature, pruning, and more.
102
+ - [Endpoint Tools](/agent-endpoint-tools) — Give the agent access to your database and APIs.
103
+ - [MCP Tools](/agent-mcp-tools) — Connect to external tool providers via the MCP standard.
104
+ - [Multi-Agent](/agent-multi-agent) — Delegate tasks to specialized sub-agents.
105
+ - [Server Hooks](/agent-server-hooks) — Save conversations, generate titles, and run server-side logic.
106
+ - [AgentChat](/AgentChat) — Configure the chat UI block.
107
+ - [AgentConversations](/AgentConversations) — Add a conversation history sidebar.
@@ -0,0 +1,54 @@
1
+ # Auth0LogoutCallback
2
+
3
+ The Auth0LogoutCallback can be used to log the user out from Auth0 when logging out of the Lowdefy app. The callback takes a `returnToPageId` property, which is the pageId the user will be directed to after logout from Auth0 is complete. The URL which the user will be directed to needs to be configured with Auth0 as an allowed logout URL.
4
+
5
+ To trigger the Auth0 logout, the `Logout` action `callbackUrl.url` param should be set to `AUTH0_LOGOUT`.
6
+
7
+ #### Properties
8
+
9
+ ###### object
10
+ - `issuer: string`: Auth0 issuer URL. This should be the same that was used for the `Auth0Provider`.
11
+ - `clientId: string`: Auth0 client ID. This should be the same that was used for the `Auth0Provider`.
12
+ - `returnToPagedId: string`: The pageId in the Lowdefy application to which the user should be redirected affter logging out from Auth0.
13
+
14
+ #### Examples
15
+
16
+ ###### Configuring Auth0LogoutCallback.
17
+
18
+ ```yaml
19
+ lowdefy: 7.0.0
20
+ providers:
21
+ - id: auth0
22
+ type: Auth0Provider
23
+ properties:
24
+ clientId:
25
+ _secret: AUTH0_CLIENT_ID
26
+ clientSecret:
27
+ _secret: AUTH0_CLIENT_SECRET
28
+ issuer:
29
+ _secret: AUTH0_ISSUER
30
+ callbacks:
31
+ - id: auth0_logout
32
+ type: Auth0LogoutCallback
33
+ properties:
34
+ clientId:
35
+ _secret: AUTH0_CLIENT_ID
36
+ issuer:
37
+ _secret: AUTH0_ISSUER
38
+ returnToPagedId: logged-out
39
+ ```
40
+
41
+ The Auth0 allowed logout URLS should be set to `https://my-app.com/logged-out` for production and `http://localhost:3000/logged-out` for development.
42
+
43
+ ###### Logging out.
44
+ ```yaml
45
+ id: logout_button
46
+ type: Button
47
+ events:
48
+ onClick:
49
+ - id: logout
50
+ type: Logout
51
+ params:
52
+ callbackUrl:
53
+ url: AUTH0_LOGOUT
54
+ ```