Skip to main content

Artifact Templates

An artifact template says what one kind of artifact holds, such as an incident report or a list of dependency updates. When an agent names a template in its artifacts field, the agent gets a tool that saves an artifact of that kind. A template can also check the artifact's content against a JSON Schema, and draw the content as a page instead of a JSON tree.

This page shows how to write a template. For a step-by-step example, see Return Structured Results and Artifacts. To see the artifacts field with the other agent fields, see the Agent and Trigger Reference.

How the pieces fit​

FileRequiredWhat it does
TEMPLATE.mdYesNames the template and its format. Its text tells the agent how to write the artifact.
schema.jsonNoThe JSON Schema of the content. Autoheal refuses content that does not match. JSON templates only.
renderer.liquidNoHTML with Liquid tags. The app fills it with the content and shows the page. JSON templates only.

Each template in artifacts gives the agent a tool named create_artifact_<id>. Dashes in the id become underscores, so the template dependency-report gives the tool create_artifact_dependency_report. The tool has three parameters:

  • title: the artifact's title. The agent chooses it.
  • summary: a short summary. Optional.
  • content: the artifact's content. With a schema.json, this parameter has the schema's shape. Without one, it is text in the template's format.

The agent can use the tool only if its system_tools filter keeps create_artifact. See Tools and integrations.

Where a template lives​

A template is a folder. The folder name is the template id: lowercase letters, digits and single hyphens, at most 100 characters.

FolderWho can use itHow artifacts names it
agents/<agent>/artifact-templates/<id>/Only that agent./artifact-templates:<id>
artifact-templates/<id>/Every agent in the projectartifact-templates:<id>, or only <id>
YAML
artifacts:
- ./artifact-templates:dependency-report # agents/<agent>/artifact-templates/dependency-report/
- incident-summary # artifact-templates/incident-summary/

autoheal agents push pushes the agent's own templates with the agent. To add or change a project template, use the editor in the app.

A template with an error, such as a missing format or a schema that does not compile, cannot be used. An agent that names it cannot start a new run until you fix it, and push prints the error. See Errors in what the agent uses.

TEMPLATE.md​

TEMPLATE.md starts with YAML front matter. The text after it is the template's guidelines.

FieldRequiredDescription
formatYesThe content's MIME type: application/json, text/markdown, text/html, text/csv or text/plain. A short name such as json or markdown is an error.
nameNoThe template's title in the app.
descriptionNoWhat the artifact is.
idNoLeave it out. The folder name is the id. A different id gives a warning.

The agent sees the template as its tool's description: the description, then the guidelines, then the format. Write the guidelines for the agent. Say which fields to fill, how to write each one, and what to leave out.

schema.json​

schema.json is the JSON Schema of the artifact's content. The agent gets it as the shape of its tool's content parameter, so the agent sees each property's description. When the content does not match the schema, Autoheal refuses to save the artifact. The agent gets the reason, with the field that failed, and can try again.

These rules apply:

  • The template's format must be application/json. A schema in a template of any other format is an error.
  • The root must describe an object: type is "object", a list that includes "object", or not set.
  • The file can be at most 256 KiB.
  • A $ref must point inside the same file, as a JSON pointer such as "#/$defs/update". A reference to a URL, to a file, or to an anchor such as "#node" is an error.
  • Checking one value can apply at most 1,000 subschemas, counted through allOf, anyOf, oneOf, if/then/else and $ref. A schema cannot refer to itself without moving to a property or an item. Typical schemas are far below this limit.

renderer.liquid​

renderer.liquid is HTML with Liquid tags. The app fills it with the artifact's content and shows the page where it would show the JSON tree. A View raw JSON toggle above the page shows the content itself.

The template's format must be application/json. A schema is optional, but with a schema the content has the shape that the renderer expects. Use {% if %} for a field that the schema does not require.

What a renderer can read​

VariableWhat it holds
dataThe artifact's content. Write {{ data.repository }} for the field repository.
artifact.evidence_urlThe address of the agent run that made the artifact, ending in toolCall=. Add an evidence id without its #, such as ev-r5683, to link to that tool call in the run. Empty when no agent run made the artifact.

No other variable exists. {{ repository }} and {{ title }} render as nothing, and nothing warns you. The artifact's title is not in scope either: if the page needs a heading, put it in the schema.

Rules​

  • Every {{ }} is HTML-escaped. Add | raw to output one value as HTML.
  • Only Liquid's standard filters exist. An unknown filter is an error.
  • {% include %}, {% render %} and {% layout %} find nothing.
  • A render stops when it takes more than one second, or writes more than about 10 MB.
  • The file can be at most 256 KiB.

What the page can do​

The page is shown in a frame that runs no scripts. A <script> tag or an on* attribute does nothing.

  • Styles: inline only, in a <style> tag or a style attribute.
  • Images: data: URLs only. The page fetches nothing.
  • Links: an http or https link opens in a new tab. A #fragment link scrolls the page. Any other link does nothing.

Style kit​

The page starts with the app's fonts (Instrument Sans, and JetBrains Mono for code), base styles for headings, lists, code, pre and tables, and the names below. Their colors follow the app's light or dark theme, so use them instead of fixed colors. Your own <style> can add to them or override them.

NameUse
ak-pageA padded page column
ak-overlineA small uppercase label above a heading
ak-mono, ak-mutedMonospace text, muted text
ak-cardA bordered card
ak-gridA grid of cards
ak-badgeA badge. Add data-tone="neutral", "info", "success", "warning" or "danger"
ak-meterA bar: <span class="ak-meter"><span style="width: 40%"></span></span>. Takes data-tone too
--ak-bg, --ak-surface, --ak-fg, --ak-muted, --ak-border, --ak-border-strong, --ak-linkPage colors
--ak-<tone>-bg, --ak-<tone>-fg, --ak-<tone>-borderBadge colors for each tone
--ak-success-mark, --ak-warning-markSolid colors for dots, bars and icons
--ak-terminal-bg, --ak-terminal-fg, --ak-terminal-mutedCommand blocks, dark in both themes
--ak-shadow-tintThe color the app mixes card shadows from

When a renderer fails​

Autoheal does not parse the Liquid when you push. A field name with a typo renders as nothing. A Liquid parse or render error shows the JSON view, with the line "This template's renderer failed:" and the error above it.

Other renderer problems are warnings on the template, not errors on the agent, so push does not print them. The template still works, without its renderer. The template's page in the app lists them:

  • The template's format is not application/json.
  • renderer.liquid is larger than 256 KiB, or is not UTF-8 text.
  • The folder also has a renderer.html. That name is reserved for a future kind of renderer.

Which renderer an artifact uses​

An artifact always renders with the template version that it was created with. When you add or change a renderer, only artifacts created after that commit use it. Run the agent again to see your change.

A complete example​

This agent reads a repository and saves one report of the dependency updates it needs. It changes nothing. The template is the agent's own.

agents/dependency-fixer/agent.yaml
apiVersion: agents.autoheal.ai/v1
name: Dependency Fixer
description: Finds vulnerable dependencies in one repository and reports the updates that fix them.
instructions: >-
Find the repository's vulnerable dependencies, then save one
dependency-report artifact that lists the update each one needs.
system_tools: operation_type == "read" || name == "create_artifact"
integration_tools: operation_type == "read"
artifacts:
- ./artifact-templates:dependency-report

The template folder is agents/dependency-fixer/artifact-templates/dependency-report/.

TEMPLATE.md
---
name: Dependency report
description: The dependency updates that fix one repository's vulnerability alerts.
format: application/json
---

Write one report per repository.

- `summary`: one or two sentences. Say how many alerts the updates would fix, and which alerts no update fixes and why.
- `updates`: one entry for each package to update. Give the version in use, the first version that fixes its alerts, and the highest severity of those alerts.
schema.json
{
"type": "object",
"required": ["repository", "summary", "updates"],
"properties": {
"repository": {"type": "string", "description": "The repository, as owner/name."},
"summary": {"type": "string", "description": "One or two sentences: what the updates would fix, and what no update fixes."},
"updates": {
"type": "array",
"items": {"$ref": "#/$defs/update"}
}
},
"$defs": {
"update": {
"type": "object",
"required": ["package", "from", "to", "severity"],
"properties": {
"package": {"type": "string"},
"from": {"type": "string", "description": "The version in use now."},
"to": {"type": "string", "description": "The first version that fixes the alerts."},
"severity": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
"advisory_url": {"type": "string", "description": "The advisory of the most severe alert the update fixes."}
}
}
}
}
renderer.liquid
<div class="ak-page">
<p class="ak-overline">Dependency report</p>
<h1>{{ data.repository }}</h1>
<p class="ak-muted">{{ data.summary }}</p>
<table>
<thead><tr><th>Package</th><th>Version</th><th>Severity</th></tr></thead>
<tbody>
{% for update in data.updates %}
<tr>
<td class="ak-mono">
{% if update.advisory_url %}<a href="{{ update.advisory_url }}">{{ update.package }}</a>{% else %}{{ update.package }}{% endif %}
</td>
<td class="ak-mono">{{ update.from }} → {{ update.to }}</td>
<td>
{% case update.severity %}
{% when "critical", "high" %}{% assign tone = "danger" %}
{% when "medium" %}{% assign tone = "warning" %}
{% else %}{% assign tone = "neutral" %}
{% endcase %}
<span class="ak-badge" data-tone="{{ tone }}">{{ update.severity | capitalize }}</span>
</td>
</tr>
{% else %}
<tr><td colspan="3" class="ak-muted">No updates.</td></tr>
{% endfor %}
</tbody>
</table>
</div>

The agent could save this content. The renderer shows it as a heading, the summary, and a table with two rows.

sample.json
{
"repository": "acme/payments",
"summary": "These updates would fix 3 of 4 alerts. The lodash alert stays: 4.17.21 breaks the build.",
"updates": [
{"package": "axios", "from": "1.6.0", "to": "1.7.4", "severity": "high", "advisory_url": "https://github.com/advisories"},
{"package": "golang.org/x/net", "from": "0.17.0", "to": "0.23.0", "severity": "medium"}
]
}

Autoheal tests this example: it checks the template the way push does, and renders the sample with the app's renderer.