AgentAssistant Answer Formats

This document provides a comprehensive reference for all expected output formats used by AgentAssistant, with particular focus on hyperlink generation patterns for information sources.

Table of Contents

  1. Overview
  2. Source Reference Formats
  3. Document Links
  4. Knowledge Graph References
  5. Innovator References
  6. HTTP/HTTPS References
  7. Skill/Function References
  8. Hyperlink HTML Patterns
  9. info-source Links
  10. http-source Links
  11. img-source Images
  12. Output Structure
  13. Examples
  14. Critical Rules

Overview

AgentAssistant produces answers using HTML-only formatting with specific patterns for citing sources. All visible formatting must use HTML elements only (no Markdown shorthand), and the entire HTML payload must be wrapped in a Markdown code fence labeled html for transport.

Source Reference Formats

Document Links

There are two forms of document link used in Thalabus. Both identify the same underlying document/chapter/paragraph nodes in Neo4j and are rendered by AgentPresenter as interactive source badges.

Canonical Document Link (doc://)

The full URI form, used by AgentAssistant when citing sources inline at the end of paragraphs:

Format: doc://docid-N[-cM][-pK][?id=HTML_IDs]

Segment Required Description
doc:// yes URI scheme prefix
docid-N yes Document identifier (e.g., docid-17)
-cM no Chapter index, 0-based (e.g., -c2 = chapter 3)
-pK no Paragraph index within chapter, 0-based (e.g., -p3 = paragraph 4)
?id=HTML_IDs no Comma-separated HTML element IDs inside the fragment (e.g., ?id=text-21,text-22)

Examples: - doc://docid-17 — document root - doc://docid-17-c2 — chapter-level - doc://docid-17-c2-p3 — paragraph-level - doc://docid-17?id=text-5 — with HTML element ID - doc://docid-17-c2-p3?id=text-21,text-22 — multiple element IDs

Bare Document Link (docid-)

A shorter form without the doc:// prefix. It appears in LLM-generated prose (e.g., section headings like "Main Garden Activities (docid-113-c0)") and in internal tool outputs. AgentPresenter automatically detects and converts bare links to [doc://...] badge arrays before rendering.

Format: docid-N[-cM[-pK]]

Segment Required Description
docid-N yes Document number (e.g., docid-113)
-cM no Chapter index, 0-based
-pK no Paragraph index within chapter, 0-based; only valid together with -cM

Examples: - docid-113 — document root - docid-113-c0 — first chapter - docid-113-c0-p2 — third paragraph of the first chapter

Note: Bare links do not support the ?id= query parameter. If element-level precision is needed, use the full doc:// form.

Knowledge Graph References

Canonical format: kg://<entity_id>[?name=Entity_Name&alias=Entity_Alias]

Examples: - kg://charly — basic entity reference - kg://bob?name=Bob_the_Dog&alias=Bobby — with name and alias

Innovator References

Canonical format: inno://<entity_id>[?name=Entity_Name&alias=Entity_Alias]

inno:// is a variant of the kg:// scheme used specifically for Innovator knowledge-graph nodes (imported from the EAM/Innovator ontology). In Neo4j these nodes carry the dual label :Entity:Innovator (plus any additional domain label, e.g. :Entity:Innovator:Diagram) rather than plain :Entity. The identifier, query parameters, and resolution rules are otherwise identical to kg:// references.

Examples: - inno://inno-42 — basic Innovator entity reference - inno://inno-42?name=Vehicle_Return_Process — with name

HTTP/HTTPS References

Canonical format: http://... or https://...

Examples: - https://www.example.com - http://mid-server.tail443ae8.ts.net:16208

Skill/Function References

Canonical format: skill://<skill_name>/<instance_id>

Examples: - skill://WeatherInfo/6 - skill://DocumentChangeManager/5

Hyperlink HTML Patterns

info-source Links

Purpose: Highlight factual spans in answers with references to documents, knowledge graph entities, or skill outputs.

HTML format:

<b class="info-source" id="URI">text</b>

Attributes: - class="info-source" — mandatory, exactly this class only - id="URI" — canonical URI (doc://, kg://, skill://, or https://) - Include ?id=... parameter only when HTML element IDs are available in context - Multiple sources: semicolon-separated in the id attribute

Examples:

With HTML element IDs in context:

<b class="info-source" id="doc://docid-17-c2-p3?id=text-21">Berlin</b>

Without HTML element IDs:

<b class="info-source" id="doc://docid-17">answer</b>

Multiple sources:

<b class="info-source" id="doc://docid-17-c2-p3?id=text-21;doc://docid-42-c1?id=text-8;kg://entity">Whiskerville</b>

Skill reference:

<b class="info-source" id="skill://WeatherInfo/6">15° Celsius</b>

http-source Links

Purpose: Link to external web resources.

HTML format:

<a class="http-source" target="_blank" href="URL">text</a>

Attributes: - class="http-source" — mandatory - target="_blank" — mandatory (opens in new tab) - href="URL" — full URL

Example:

<a class="http-source" target="_blank" href="https://www.example.com">Example Website</a>

img-source Images

Purpose: Render diagram images from Mira agent responses.

HTML format:

<img class="img-source" src="/document/<uuid>.<extension>" alt="<diagram name>" />

Attributes: - class="img-source" — mandatory - src="/document/<uuid>.<extension>" — derived from source path by extracting filename and prefixing with /document/ - alt="<diagram name>" — human-readable name (translate to conversation language when appropriate)

Example:

<img class="img-source" src="/document/6557a902-b058-83cb-2896-9b767e0a705a.png" alt="Take back Car Diagram" />

Output Structure

Basic Answer Format

<p>Answer text with <b class="info-source" id="doc://docid-17?id=text-5">factual span</b>.</p>

With Multiple Sources

<p>Answer text with <b class="info-source" id="doc://docid-17?id=text-5;doc://docid-18?id=text-12">combined information</b>.</p>

With External Links

<p>For more information, see <a class="http-source" target="_blank" href="https://www.example.com">Example Website</a>.</p>

With Images

<p>Here is the relevant diagram:</p>
<img class="img-source" src="/document/da072bab-1fb1-e97b-1d15-6d371410d7b8.png" alt="Process Diagram" />

Blockquotes

Purpose: Display verbatim excerpts from sources.

HTML format:

<div class="blockquote" data-source="URI">
  <p id="text-8">Literal sentence…</p>
  <footer>Source: "Document title" (Paragraph 8)</footer>
</div>

Attributes: - class="blockquote" — mandatory - data-source="URI" — canonical source URI with ?id= parameter when available

Empty doc-embed shorthand (when element is already loaded in context with explicit id and no translation needed):

<div class="blockquote doc-embed" data-source="doc://docid-3?id=li-4-t-1"></div>

Examples

Example 1: Document Reference with HTML Element IDs

Context:

fragmentid=docid-7-c1
text=`<p id="text-8">Superava i periodi di guida prescritti di 10 ore di non oltre il 10%: sanzione ordinaria da € 41,00 a € 165,00.</p>`

Prompt: In caso di superamento fino al 10%, quale è la sanzione ordinaria?

Output:

<p>La sanzione ordinaria è <b class="info-source" id="doc://docid-7-c1?id=text-8">da € 41,00 a € 165,00</b>.</p>

Example 2: Multiple Sources

Context:

docid-123-c1-p2:
  text-5: "Joe lives in Berlin"
  text-7: "Mary lives in Los Angeles"
  text-8: "Mary works at Google"

Prompt: Where do Joe and Mary live?

Output:

<p>Joe lives in <b class="info-source" id="doc://docid-123-c1-p2?id=text-5">Berlin</b> and Mary lives in <b class="info-source" id="doc://docid-123-c1-p2?id=text-7,text-8">Los Angeles</b>.</p>

Example 3: Knowledge Graph Entity

Context:

kg://charly with name="Charly the Dog", alias="Charlie"

Prompt: What is Charly's fur color?

Output:

<p>Charly's fur color is <b class="info-source" id="kg://charly?name=Charly_the_Dog&alias=Charlie">white</b>.</p>

Example 4: Skill Output

Context:

FUNCTION RESULT: WeatherInfo executed successfully: {"city": "London", "temperature": 15.06, "skillid": "WeatherInfo", "instanceid": 6}

Prompt: What is the current weather in London?

Output:

<p>The current weather in London is about <b class="info-source" id="skill://WeatherInfo/6">15° Celsius</b>.</p>

Example 5: External Link

Output:

<p>For more information, see <a class="http-source" target="_blank" href="https://www.example.com">Example Website</a>.</p>

Example 6: Complete Answer with Metadata

<p>Joe lives in <b class="info-source" id="doc://docid-123-c1-p2?id=text-5">Berlin</b> and Mary lives in <b class="info-source" id="doc://docid-123-c1-p2?id=text-7">Los Angeles</b>.</p>

optional_rag_fragment_used: doc://docid-123-c1-p2?id=text-5,text-7

Critical Rules

1. HTML Element ID Inclusion (MANDATORY)

WHEN HTML ELEMENT IDs ARE AVAILABLE IN CONTEXT: - ALWAYS include them in the ?id=... parameter - Multiple element IDs: comma-separated in ?id=... - This applies to ALL <b class="info-source"> tags referencing document fragments with available IDs - The ?id= parameter goes INSIDE the URI string, NOT as a separate attribute

WRONG (missing ?id= when IDs are available):

<b class="info-source" id="doc://docid-56226" title="...">the text</b>

CORRECT (with ?id=):

<b class="info-source" id="doc://docid-56226?id=text-21">the text</b>

2. Class and Attribute Restrictions

info-source links: - ✅ class="info-source" — permitted - ❌ class="info-source highlighted-keyword" — extra classes forbidden - ❌ title="..." — extra attributes forbidden - ❌ data-element-id="..." — extra attributes forbidden

http-source links: - ✅ class="http-source" target="_blank" — required attributes - No other attributes permitted

3. Language Priority

The text content of <b class="info-source">...</b> MUST be in the conversation language. If the source fragment is in a different language, translate the text to match the conversation language. For semantically critical original-language text (legal terminology, proper nouns), include the original-language phrase in parentheses immediately after the closing </b> tag.

Example: - Source (French): "Responsabilité pénale" → Output: <b class="info-source" id="...">Criminal liability</b> (Responsabilité pénale)

4. optional_rag_fragment_used Line

Example:

optional_rag_fragment_used: doc://docid-1?id=text-1;doc://docid-2-c01?id=text-3;kg://entity_id?name=Entity_Name

5. skill vs doc Rule

Wrong:

<p>The changes to <b class="info-source" id="skill://DocumentChangeManager/5">bob-04.txt</b> have been committed.</p>

Correct:

<p>The changes to <b class="info-source" id="doc://docid-42">bob-04.txt</b> have been committed.</p>

6. Blockquote Usage

MANDATORY when quoting literal text from a source: - User asks for quote, excerpt, passage, specific text, or "link to the appropriate paragraph" - Use <div class="blockquote" data-source="URI"> wrapper - Include ?id= parameter in data-source when HTML element IDs are available

When to use doc-embed shorthand: - Element is already present verbatim in <LOADED_DOCUMENTS> context - Element has explicit id attribute - No translation needed - User asks to show, quote, or display element as-is

Summary Table

Element Class Required Attributes Optional Attributes Notes
<b> (info-source) info-source id="URI" None Highlight factual spans; include ?id= when HTML element IDs available
<a> (http-source) http-source href="URL", target="_blank" None External links
<img> (img-source) img-source src="/document/uuid.ext", alt="name" None Diagram images from Mira
<div> (blockquote) blockquote data-source="URI" None Verbatim excerpts; use doc-embed when element already loaded
<div> (doc-embed) blockquote doc-embed data-source="URI" None Empty shorthand for already-loaded elements

Last updated: 2026-07-16