KnowledgeBases

• optional

A Template Package can create (or recreate) knowledge bases during deployment.

Each knowledge base is linked to one uploaded file:

1. Add the file in manifest.files.
2. On that same file entry, add an optional knowledgebase object.

During deploy, file uploads run first. Then each knowledgebase entry is resolved to that row's _fileId and _fileVersionId, and the knowledge base is created (or skipped/recreated based on ifExists).

Knowledge bases are always created from the file version produced by this deploy's upload. If a document already exists in the environment from an earlier upload without a knowledgebase entry, you cannot point a new knowledge base at that old version alone. Include the same file again in manifest.files with a knowledgebase object (and the matching fileUploads/ payload). Deploy uploads it again, creates a new version of the file, and creates the knowledge base from that new version.

_path requirement

manifest.files[]._path is required and must be a string (empty string is valid for files at the root of fileUploads/).

For knowledge base creation to work, _path + _name must resolve to the actual uploaded file location under fileUploads/.

Examples:

• _name: "nested-kb-notes.md" with _path: "nested/docs" maps to fileUploads/nested/docs/nested-kb-notes.md
• _name: "property-mapping.md" with _path: "" maps to fileUploads/property-mapping.md

Resolution normalizes _path by trimming whitespace and removing a leading/trailing / before lookup. In practice, still provide the real relative folder path used inside fileUploads/.

knowledgebase object

Only these keys are allowed on file.knowledgebase:

• name (required): display name of the knowledge base. Agents reference this value in their knowledgebases arrays. Maps to _name in the service.
• userType (required): stable identifier. Allowed characters: letters, digits, underscores. Maps to _userType in the service.
• ifExists (optional): conflict behavior when a knowledge base with the same userType already exists. If omitted or blank, deploy treats it as default.

Any other knowledgebase property fails template validation.

ifExists

If a knowledge base with the same userType already exists:

• default (or omitted/empty): keep the existing knowledge base unchanged and skip this manifest entry.
• recreate: delete the existing knowledge base, then create it again using the newly uploaded file/version.

Values are compared case-insensitively.

update is not supported for file-linked knowledge bases. Any value other than default or recreate fails validation.

Agents

Agents attach to knowledge bases using the knowledge base name, not userType.

Use the exact value from manifest.files[].knowledgebase.name.

Complete example

// manifest.json
{
   "Template Name": "Knowledge Base Template",
   "Template Version": "1.0.0",
   "files": [
      {
         "_name": "property-mapping.md",
         "_path": "",
         "_tags": [],
         "knowledgebase": {
            "name": "property-mapping-md",
            "userType": "property_mapping_md",
            "ifExists": "default"
         }
      },
      {
         "_name": "revit-category-mapping.md",
         "_path": "",
         "_tags": [],
         "knowledgebase": {
            "name": "revit-category-mapping-md",
            "userType": "revit_category_mapping_md",
            "ifExists": "recreate"
         }
      },
      {
         "_name": "agent-bg-source.txt",
         "_path": "",
         "_tags": [],
         "knowledgebase": {
            "name": "agent-bg-md",
            "userType": "agent_bg_md",
            "ifExists": "recreate"
         }
      },
      {
         "_name": "nested-kb-notes.md",
         "_path": "nested/docs",
         "_tags": [],
         "knowledgebase": {
            "name": "nested-docs-kb",
            "userType": "nested_docs_kb"
         }
      }
   ]
}

ZIP layout (fileUploads/ paths must match _path + _name):

Knowledge Base Template.zip /
|-- fileUploads /
|   |-- property-mapping.md
|   |-- revit-category-mapping.md
|   |-- agent-bg-source.txt
|   +-- nested /
|       +-- docs /
|           +-- nested-kb-notes.md
|-- manifest.json

// agents/my-agent.json (excerpt)
{
   "knowledgebases": ["property-mapping-md", "revit-category-mapping-md", "nested-docs-kb"]
}

Deploy behavior

• File uploads run first.
• To add a knowledge base for content that already exists as a file, re-upload that file in the manifest with a knowledgebase entry so deploy can create a new file version and bind the knowledge base to it.
• If a file upload for a knowledgebase row cannot be resolved, that knowledge base is skipped and an error is written to deploy logs.
• Only manifest.files entries that include knowledgebase are used for knowledge base creation. Other file entries behave as normal uploads only.