Skip to main content
Question

What is the officially recommended workflow for enabling Atlas AI to reliably answer questions from uploaded PDF maintenance manuals

  • May 6, 2026
  • 2 replies
  • 21 views
B
Committed ⭐️⭐️
Forum|alt.badge.img+5

I uploaded a PDF maintenance manual into Cognite CDF using:

client.files.upload(...)

The document is successfully indexed by the Documents Engine.

I can confirm that:

- client.documents.retrieve_content() works
- client.documents.search() returns the document
- last_indexed_time is populated
- truncated_content contains extracted text

Example document metadata:

{
  "id": 3652062792350259,
  "external_id": "HACTL_CSS_Manual",
  "name": "HACTL_CSS_Manual",
  "title": "Hactl.md",
  "mime_type": "application/pdf",
  "last_indexed_time": "2026-05-06 14:57:28.531+00:00"
}

However, Atlas AI still responds with:

“I could not find any uploaded maintenance manuals related to wheel carriage troubleshooting in the system.”

Questions:

1. Does Atlas AI automatically use Documents Search semantic indexing from files uploaded with client.files.upload(), or does it require CogniteFile instances + upload_content()?

2. Is Atlas AI document retrieval based on:
   - Documents semantic search
   - passages/search
   - or instanceIds grounding only?

3. Could the issue be related to the document title metadata?
   Current title is:
   "Hactl.md"

4. Is there an official way to update the Documents title after indexing?

5. For Atlas AI grounding, what is the recommended ingestion architecture?
   - Files.upload()
   - upload_content(instance_id=...)
   - CogniteFile
   - Documents Search
   - or instanceIds?

6. What is the officially recommended workflow for enabling Atlas AI to reliably answer questions from uploaded PDF maintenance manuals?

    2 replies

    Mithila Jayalath
    Expert ⭐️⭐️⭐️⭐️
    Forum|alt.badge.img+8
    • Mithila Jayalath
    • Expert ⭐️⭐️⭐️⭐️
    • May 7, 2026

    ​@kelvin will you be able to help out here?

    kelvin
    Expert ⭐️⭐️⭐️⭐️
    • kelvin
    • Expert ⭐️⭐️⭐️⭐️
    • May 12, 2026

    Hi ​@Bruce Gee! Thanks for the questions!

    1. Does Atlas AI automatically use Documents Search semantic indexing from files uploaded with client.files.upload(), or does it require CogniteFile instances + upload_content()?

    Yes, Atlas AI requires the file to be in Data Modeling. Learn more here: https://docs.cognite.com/cdf/dm/dm_guides/dm_integrate_files

     

    2. Is Atlas AI document retrieval based on:
       - Documents semantic search
       - passages/search
       - or instanceIds grounding only?

    Atlas AI has two document specific tools (see documentation here):

    1. Answer document questions
    2. Summarize documents

    Both of these require the set of relevant file instance IDs to be known. For the agent to first find the candidate files, it needs either of the knowledge graph tools, Query Knowledge Graph or Query (preview). 

    This helps the agent scope down to the relevant parts of the knowledge graph (asset hierarchy or otherwise) before performing the RAG or summarization.

    The Query Knowledge Graph can also search for files by keywords in the file content. This will come to the Query tool soon.

    The document tools use these API under the hood:
    Ask: https://docs.cognite.com/20230101/document-ai/ask-questions-about-one-or-more-documents

    Summarize: https://docs.cognite.com/20230101/document-ai/summarize-documents

     

    3. Could the issue be related to the document title metadata?
       Current title is:
       "Hactl.md"

    The file metadata should not be a problem. The agent needs to know or be able to find the space and externalId of the file to use it with Ask documents or Summarize documents.

    The document tools does not support markdown files. 

     

    4. Is there an official way to update the Documents title after indexing?

    You can update the file name in the same way you created the file in the first place. See link to how to use files in data modeling in answer to question 1.

     

    5. For Atlas AI grounding, what is the recommended ingestion architecture?
       - Files.upload()
       - upload_content(instance_id=...)
       - CogniteFile
       - Documents Search
       - or instanceIds?

    Please elaborate. Atlas agents can be grounded in documents represented as CogniteFile (files in data modeling, with instanceId). The agent does not have access to the full file content, but only metadata and Answer and Summarize.

     

    6. What is the officially recommended workflow for enabling Atlas AI to reliably answer questions from uploaded PDF maintenance manuals?

    As elaborated above. If you always want to reference a specific document, include that instanceId (space, externalId) in the prompt, and instruct the agent to always use the “ask document” tool to get answers to questions about it.

     

    Hope this helps!

    Terms & ConditionsAccessibility statement