Knowledge Asset Generation — User Guide

An 80-page regulation answers any question — as long as someone has the time to read it end to end. Knowledge Asset Generation turns documents already ingested into a context into consultation-ready material: a rewritten plain-language version, an FAQ and a glossary of terms and acronyms. Everything is born as a draft and only goes into use after a person reviews and approves it — you get scale without losing control.

This guide covers generation and the asset lifecycle. Review and approval have their own guide: Knowledge Curation. The architecture of the feature is in Architecture — Knowledge Preparation.

1. What each asset type is

When requesting generation through an integration, the types accept either the lowercase name above or the enum name (DOCUMENTO_OTIMIZADO, FAQ, GLOSSARIO).

2. Cited sources — why you can trust it

Generation uses strict grounding in the sources: the language model receives only the document's text (the already-indexed excerpts, identified by [chunk:<id>]) and is required to cite, in every section, question/answer and term, the source excerpts (chunkIdsOrigem) that support that item.

After generation, a programmatic validation (not done by AI) checks every citation against the document's real excerpts:

• a citation of a nonexistent excerpt is removed;
• an item with no valid citation is discarded;
• if no item remains, that type fails for that document with a readable reason ("O modelo não produziu conteúdo aproveitável...") — without bringing down the rest of the batch.

On the curation screen, the reviewer sees the asset side by side with the cited source excerpts, precisely to validate this grounding before approving.

3. How to trigger a generation

Generation is triggered through a programmatic integration — the platform exposes an endpoint that receives the batch and immediately returns a task identifier (taskId), running the work in the background. The contracts are in the API reference. The curation screen has no batch-generation button: from there you trigger only the one-off re-generation of a specific asset.

It requires the KNOWLEDGE_ASSET_GENERATE permission (admin and steward/ADVANCED_USER profiles by default).

Batch rules:

• the destination context is mandatory (dominio field) — it is never guessed;
• the documents (documentCodes) are optional: left empty, every document in the context that already has indexed excerpts is included, capped at 50 documents per batch (configurable). A larger batch gets a message in Portuguese asking you to split it;
• the types (tipos) are optional: left empty, all three are generated.

Following the progress

Real-time follow-up is an event stream (text/event-stream, event generation-progress) that emits the task state on every change: the phase (descobrindo-documentos, gerando), total, processados, falhas, ativosGerados, the latest messages (e.g. "«Portaria X»: faq v1 gerado com 8 item(ns).") and the final state COMPLETED or FAILED.

The task state stays available for 6 hours and survives reconnections. After that, the query returns NOT_FOUND with the message "Tarefa não encontrada ou expirada.".

Re-generation

Re-generation creates a new version (same document, same type) — the previous version is not altered. It also happens automatically through the monitored-sources cascade: when a document is replaced at its origin, the platform deprecates the approved assets of the old version and generates new assets for the new version, which return to the curation queue.

4. Practical example — from document to approved FAQ

1. The regulations context received "Instrução Normativa 2.055" through URL ingestion. Ingestion finished and the excerpts are indexed.
2. A user with the generation permission triggers a batch for that context requesting all three asset types, and receives the task identifier.
3. While the batch runs, the follow-up shows the phase and the score: 1 document, 3 assets generated, 0 failures — up to COMPLETED.
4. On the Knowledge Curation screen, the three drafts appear in the review queue. The reviewer checks the citations side by side, adjusts one glossary definition and approves with Aprovar.
5. With the approval, the FAQ and the glossary start counting for chat search — if asset consumption is enabled in the context.

5. Browsing assets

The paginated listing (with filters by context, type and status) and the detail of each asset are available on the curation screen and also through an integration — see the API reference. The listing returns the items along with the total and the page and page size requested.

Every asset carries full traceability: source document (documentCode), cited excerpts per item (chunkIdsOrigem), AI model (modeloLlm) and prompt version (promptVersao) used, asset versao, geradoEm, whether it was human-edited (editadoPorHumano), who approved it (aprovadoPor) and the recorded reason (reason).

6. Lifecycle (status)

DRAFT ──> APPROVED ──> DEPRECATED
  └─────> REJECTED

An invalid transition is refused with a message explaining the allowed transitions. Every status change generates a lineage event (ASSET_APPROVED / ASSET_DEPRECATED) with the real actor.

Glossary terms: generated terms show up in the catalog as DRAFT and do not affect chat query expansion until they are approved on the curation screen (chat resolution only uses approved terms; the change propagates within up to 5 minutes through the cache).

Use in chat/search: on approval, the asset is indexed (with semantic vectors) in the context's knowledge index — but the chat only queries that index if the administrator turns on the useKnowledgeAssets option in the context configuration (off by default). With the option off, search behaves exactly as it did before the feature.

7. Permissions

Without the permission, the operation is denied with a message in Portuguese and the denial is audited.

8. Troubleshooting