7049a874f3
Open-source release of MAESTRO, an agent orchestration platform that runs LLM-driven tasks through sandboxed tools, with a web UI. Apache-2.0. See README.md and docs/ (getting-started, configuration, architecture).
109 lines
3.1 KiB
Markdown
109 lines
3.1 KiB
Markdown
# RenderUserTemplate
|
|
|
|
Renders a template from `templates/` by substituting `{{var}}` placeholders with caller-supplied params.
|
|
|
|
## Overview
|
|
|
|
Companion to `ReadUserTemplate`. Instead of returning the raw body, this tool:
|
|
|
|
1. Parses the template's frontmatter `params` spec (same shape as scripts / browser-macros).
|
|
2. Validates caller-supplied `params` against the spec (type-check + defaults applied).
|
|
3. Replaces every `{{name}}` placeholder in the body with the resolved value.
|
|
4. Returns the rendered body (no `# Template:` header, no frontmatter — just the substituted text).
|
|
|
|
Placeholders **not declared** in `frontmatter.params` are left literal — so prose like
|
|
`use {{column}} as the key` survives unchanged when no `column` param exists.
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
Template file `templates/weekly-report.md`:
|
|
|
|
```markdown
|
|
---
|
|
description: Weekly status report
|
|
params:
|
|
- name: date
|
|
type: string
|
|
- name: summary
|
|
type: string
|
|
default: "(no summary)"
|
|
---
|
|
# Status — {{date}}
|
|
|
|
{{summary}}
|
|
```
|
|
|
|
Call:
|
|
|
|
```json
|
|
{ "name": "weekly-report", "params": { "date": "2026-05-11", "summary": "shipped 3 PRs" } }
|
|
```
|
|
|
|
Response:
|
|
|
|
```
|
|
# Status — 2026-05-11
|
|
|
|
shipped 3 PRs
|
|
```
|
|
|
|
---
|
|
|
|
## Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `name` | string | Yes | Template filename, with or without `.md` extension (max 128 chars) |
|
|
| `params` | object | No | Key-value params matching the template's `frontmatter.params` spec |
|
|
|
|
---
|
|
|
|
## Frontmatter `params` schema
|
|
|
|
Identical to scripts / browser-macros:
|
|
|
|
```yaml
|
|
params:
|
|
- name: identifier # must match /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
|
|
type: string | number | boolean
|
|
description: optional
|
|
default: optional # if omitted, the param is required
|
|
```
|
|
|
|
Param values are coerced to string via `String(value)` when substituted.
|
|
|
|
---
|
|
|
|
## Error cases
|
|
|
|
- `name` missing or invalid characters → error.
|
|
- Template file does not exist in `templates/` → error.
|
|
- Frontmatter is malformed (bad YAML, bad `params` shape) → error.
|
|
- A required param (no default) is missing from the call → error: `param X: required but not provided`.
|
|
- A param has the wrong type → error: `param X: expected number, got string`.
|
|
|
|
Templates without any frontmatter render as pure pass-through — any `{{var}}` stays literal.
|
|
|
|
---
|
|
|
|
## Use cases
|
|
|
|
- Weekly / monthly reports: `RenderUserTemplate({ name: "weekly-report", params: { date, summary } })`.
|
|
- Email canned responses with variable substitution.
|
|
- Code boilerplate with a few configurable parts (component name, props).
|
|
|
|
For more dynamic logic (conditionals, loops), open `ReadUserTemplate` and do the substitution
|
|
inline in your output — there is no Handlebars / Liquid / etc. engine, by design.
|
|
|
|
---
|
|
|
|
## Related tools
|
|
|
|
- `ReadUserTemplate` — returns the raw body + frontmatter. Use this when you want to inspect
|
|
the template structure or do substitution yourself.
|
|
- `ListUserAssets({ kind: "templates" })` — list available templates.
|
|
- `RunUserScript` — for executable scripts (not just text substitution).
|
|
- This tool is a META_TOOL — no need to add it to `allowed_tools` in piece YAML.
|