RDBTC-223 Guide: AI Agent Attachments Fixes

Author: Netzach-Nyss

guides/ai-agents-attachments.mdx

@@ -1,6 +1,6 @@
 ---
-title: "File Attachments in RavenDB AI Agents"
-tags: [ai, attachments, csharp, demo]
+title: "Beyond Text: Adding File Attachments to RavenDB AI Agents"
+tags: [ai, attachments, csharp, demo, use-case]
 icon: "ai-agents"
 description: "Learn how to attach binary files such as PDFs and images to RavenDB AI Agent conversations, reducing token usage while keeping files accessible across the conversation lifecycle."
 publishedAt: 2026-04-15
@@ -41,7 +41,7 @@ RavenDB AI Agents are LLM-powered components integrated into your database, desi
 What makes RavenDB’s approach different is that the intrinsic complexity is handled for you. The database server manages conversation state, integrates with LLM providers, and enforces safety through Query and Action tools defined by the developer. This means the agent can only perform operations you explicitly allow, keeping it predictable and controlled. Instead of building infrastructure around agents, you focus on defining capabilities and letting RavenDB handle the rest. If you want to look into AI Agents more, you can check our [AI Agents deep dive](https://ravendb.net/articles/practical-look-at-ai-agents-with-ravendb).  
 </Admonition>
 
-## Attachment method
+## Attaching files to a conversation
 
 Attaching a file is as simple as calling `AddAttachment` on the conversation and passing the file. The first file is attached to the conversation, granting your Agent access to it. LLM then provides a summary of the payload's content, which is included in the chat context (the context window is how much of the conversation the LLM can remember at once before older parts are dropped), and the LLM can reuse this summary later. This process makes the Agent reduce the usage of tokens burnt for each file.
 
@@ -80,21 +80,31 @@ But how does it look in practice? Let’s look at the demo.
 
 ### Demo
 
+<Admonition type="note" title="Run This Demo Yourself"> 
 Before we begin, if you want to run this demo yourself, you can find the [samples-hr repository on GitHub](https://github.com/ravendb/samples-hr). Instructions for launching it are included.
+</Admonition>
+
+The demo application is a small HR chatbot where employees can submit expense reports and handle everyday HR tasks through a conversation with an AI agent, rather than filling in forms. You can impersonate any employee from the selector at the top of the chat window, for demo convenience. It connects to RavenDB and uses a set of Query and Action tools to look up employee data and create expense documents on the user's behalf. 
+
+<Image img={require("./assets/ai-agent-attachment1.webp")} alt="HR Assistant welcome screen with the employee selector dropdown open and Mike Thompson highlighted, with the Bills Menu button visible at the bottom left" />
+
+The bills menu hidden under the left-side button is there for demo convenience only. In a real app files would come from any binary stream the user provides.
+
+<Image img={require("./assets/ai-agent-attachment2.webp")} alt="HR chatbot chat window with the bills menu open, showing available receipts including the TechConf 2026 expense" />
 
 Let’s step into Mike Thompson’s role by selecting him at the top of the chat window. After returning from a business trip, we want to report our expenses to HR. Instead of filling out forms, we simply open the HR chatbot that handles these everyday tasks, reducing the time HR needs to process routine requests and making the whole experience quicker and more comfortable for users.
 
 From the bills menu on the left of chat (added here just for presentation, since files can be any binary stream), we attach the TechConf 2026 receipt and tell the chatbot we’d like to report it (1). Once we send the message, the LLM processes the request (2). After a quick confirmation that everything looks correct (3), the AI Agent uses its tools to create a new document in RavenDB on our behalf. Like that, we are done with this task and can wait for HR’s response.
 
-<Image img={require("./assets/ai-agent-attachment1.webp")} alt="HR chatbot chat window showing a TechConf 2026 receipt being attached and submitted as an expense report" />
+<Image img={require("./assets/ai-agent-attachment3.webp")} alt="HR chatbot chat window showing a TechConf 2026 receipt being attached and submitted as an expense report" />
 
 Now that our agent has accepted the file, we can enter RavenDB and take a look at the conversation collection to check how RavenDB handled things in the background. We can notice that RavenDB stored the file as a RavenDB document attachment to the conversation.
 
-<Image img={require("./assets/ai-agent-attachment2.webp")} alt="RavenDB Studio showing the conversation document with the receipt stored as a binary attachment" />
+<Image img={require("./assets/ai-agent-attachment4.webp")} alt="RavenDB Studio showing the conversation document with the receipt stored as a binary attachment" />
 
 Until the conversation expires (the default expiration for this demo is 30 days), RavenDB can revisit this file and provide context to the Agent. Thanks to another tool, RavenDB also stores data from files and creates new documents, making data easier to access.
 
-<Image img={require("./assets/ai-agent-attachment3.webp")} alt="RavenDB Studio showing the new expense document created by the AI agent from the attachment data" />
+<Image img={require("./assets/ai-agent-attachment5.webp")} alt="RavenDB Studio showing the new expense document created by the AI agent from the attachment data" />
 
 ## Summary