Attach Files in Conversations

​

Overview

Key Capabilities:

• Image Analysis: Upload images for visual analysis, OCR, content extraction, and AI-powered interpretation
• Document Processing: Attach documents for content indexing, semantic search, and information retrieval
• Data Files: Upload CSV, JSON, and other data formats for analysis and processing
• Multiple Upload Methods: Click to browse, drag-and-drop, or paste from clipboard
• Centralized Storage: All attachments stored in Artifact buckets with configurable retention policies

---

​

How Attachments Work

The attachment functionality is integrated with the Artifact Toolkit.

• Storage: Every file you attach is automatically uploaded and stored in an Artifact bucket. The backend always uses the default attachments bucket — no manual Artifact Toolkit configuration is required.
• Access: This allows the AI agent to access the file for analysis and also provides a centralized location for you to manage these files via the Artifacts section of the platform.
• Retention: Files are subject to the retention policy of the bucket they are stored in. By default, new buckets have a retention period of 30 days, after which files are automatically deleted. Retention period can be changed manually.

For detailed information about bucket management and retention policies, see the Artifacts Documentation.

---

​

Prerequisites

Before using attachments, ensure you have:

• Permission Level: Editor or Admin role within the project (required for Agent configuration)
• Active Conversation: An existing conversation or agent

---

​

Enabling Attachments

Attachments must be explicitly enabled before use.

​

Enable Attachments for Agents

Configure attachment capabilities at the Agent level to enable file uploads in all conversations using that agent.

1. Navigate to Agents from the main menu
2. Select the agent to configure
3. On the Configuration tab, locate the Allow attachments toggle in the INTERNAL TOOLS section (disabled by default)
4. Click the toggle to enable attachments
5. Save the agent

Result: The Attachments internal tool is added to the agent. The backend automatically provisions storage using the default attachments bucket — no additional toolkit configuration is required. When using this agent in a conversation, Attach Files becomes available in the + menu of the message input area.

​

Attach Files in a Conversation

Upload files directly within an active chat session without configuring the agent.

1. Open a new or existing conversation
2. Click the + button in the message input toolbar
3. Click Attach Files at the top of the menu
4. The file browser opens — select and confirm your files

Result: Attachments are immediately available. No additional setup is required. Upload options

​

Using Agents with Attachments in Conversations

The availability of Attach Files in the + menu is determined by the currently active participant.

• If the active agent or pipeline has Allow attachments enabled, Attach Files is active in the + menu
• If you switch to an agent or pipeline without attachments enabled, Attach Files is disabled and shows the tooltip: “Attachments aren’t available for the selected agent or pipeline.”
• In direct LLM or dummy conversations (no agent selected), Attach Files is always active

---

​

Using Attachments in Conversations

When attachments are available — either because you are in a direct LLM chat or using an agent/pipeline with Allow attachments enabled — the + button in the message input toolbar gives access to Attach Files. Send Message with Attachments

1. After attaching files, thumbnails appear above the message input area
2. Type a text prompt describing what you want the AI to do (required)
3. Click the Send button

​

Manage Attachments in Chat

View Attachments

• Sent attachments display as clickable thumbnails in the chat history
• Click any thumbnail to view the full-size image or preview the file

Download or Delete Attachments

1. Hover over any attachment thumbnail in the chat
2. Two icons appear:
   • Download icon: Save the file to your local system
   • Delete icon (trash can): Remove the attachment
   

​

Delete Attachments

When clicking the delete (trash can) icon, a confirmation dialog provides two deletion options: Option 1: Delete from Chat Only (default)

• Removes the thumbnail from the conversation
• Original file remains in the Artifact bucket
• File remains accessible via the Artifacts menu

Option 2: Delete from Chat and Storage

• Check the box: “Also delete from attachment storage”
• Removes the thumbnail from the conversation
• Permanently deletes the file from the Artifact bucket
• File cannot be recovered

---

​

Working with Non-Image Files

Non-image file attachments follow a different processing workflow than images. While images are analyzed directly by the LLM’s vision capabilities, other file types are indexed for semantic search and retrieval. Processing Workflow:

1. Upload: File is uploaded to the default attachments bucket
2. Indexing: File content is automatically extracted and indexed into a vector database
3. Retrieval: When you query, relevant content is retrieved through semantic search

Key Differences from Images: Shared Collection Behavior All non-image attachments are indexed into the same storage collection in the default attachments bucket. Implications:

• Search results may include content from previously attached files (if using the same toolkit)
• Queries might retrieve information from multiple uploaded files
• Results may include content you didn’t intend to search

Recommendations:

1. Be specific in queries to avoid retrieving irrelevant content from other files
2. Include context in queries to help narrow down relevant content
3. Reference filenames when querying if you need content from a specific file

Usage Tips

Structure your queries effectively

Instead of asking “What does the file say?”, ask “What are the recommended security practices mentioned in the uploaded security guidelines?”

Include context in your prompt

Reference the file type or subject: “In the uploaded project plan, what are the Q2 milestones?”

Query for specific sections

Ask for particular information: “Find all mentions of API rate limits in the uploaded documentation”

Use keywords from your files

If you know specific terms appear in your files, include them in queries to improve retrieval accuracy

---

​

Supported File Types and Limits

Image Formats Raster images are sent directly to the LLM for visual analysis. Supported formats include: Documents & Data Files Documents and data files are indexed into a vector database for semantic search and retrieval. Supported types include: Programming & Code Files Source code files are indexed and their content is made available for AI analysis. Supported languages include: File Size and Quantity Limits

---

​

FAQ

Where are my attached files stored?

All attachments are stored in the default attachments bucket. You can view and manage these files from the Artifacts menu in the main navigation.

How long are files stored?

By default, new Artifact buckets have a 30-day retention period. Files older than the retention period are automatically deleted. You can view and modify retention periods from the Artifacts page.

Can I use attachments with multiple agents in one conversation?

Yes. In conversations, all attachments are saved to the default attachments bucket. All agents participating in that conversation can access the chat history, including attachments. Which agents can process attachments depends on their individual configuration — only agents with Allow attachments enabled can actively use attached files.

Can I recover a deleted attachment?

No. Deletion is permanent. If you delete a file from the Artifacts bucket or use the “Also delete from attachment storage” option in chat, it cannot be recovered.

Why can't I send a message with only an attachment and no text?

The system requires a text prompt to provide context about how the AI should interpret or process the attachment(s). The Send button activates only after you enter text.

How many tokens does an image consume?

Token consumption varies by LLM provider:

• Claude (Anthropic): Fixed number of tokens per image (consult model documentation)
• GPT (OpenAI): Varies based on image size and resolution

Check your LLM provider’s documentation for specific token costs.

What happens when I attach the same filename twice?

Duplicate filenames are handled automatically. The system renames the new file by appending a timestamp and file size (e.g., image_20251106_143022_1.50KB.png). Both files are preserved in the bucket with distinct names — no error is shown and no data is overwritten.

Can I use attachments in Pipeline conversations?

Yes. Pipelines support the Allow attachments toggle in their INTERNAL TOOLS section. When enabled, the toggle adds attachments to the pipeline’s internal tools and also adds an input_attachments state variable to the pipeline YAML. Once enabled, the paperclip icon becomes active when using that pipeline in a conversation.

---

​

Troubleshooting

File size exceeds image limit

Error: Image is rejected when attachingCause: The image exceeds the 5 MB per-image size limit (SVG files are exempt).Solution:

1. Compress or resize the image below 5 MB
2. For SVG files, the size limit does not apply
3. Re-attach the file

Attach Files is disabled or shows a tooltip in the + menu

Symptom: Clicking + shows Attach Files with the tooltip “Attachments aren’t available for the selected agent or pipeline.”Cause: The active agent or pipeline does not have Allow attachments enabled.Solution:

1. Enable Allow attachments on the agent via its Configuration tab (see Enabling Attachments above)
2. Verify you have the required permissions to edit the agent configuration
3. Contact a project administrator if permissions are insufficient

Unexpected filename in chat after upload

Symptom: Attached file appears with a different name than the original (e.g., image_20251106_143022_1.50KB.png)Cause: A file with the same name was already attached. The system automatically renames duplicates with a timestamp and file size suffix to avoid overwriting existing files.Solution: This is expected behavior. Both files are preserved. Use unique filenames if you need to distinguish uploads easily.

Attachment visible in chat but not found in Artifacts

Symptom: Thumbnail appears in chat, but file is missing from Artifacts menuPossible Causes:

• File was deleted directly from the Artifacts page
• Retention period expired and file was auto-deleted

Solution: Files deleted from Artifacts cannot be recovered. Re-upload if needed.

Cannot delete attachment with Also delete from attachment storage option

Error: Deletion fails when “Also delete from attachment storage” is checkedPossible Causes:

• File was already deleted from the bucket via the Artifacts page

Solution:

1. Uncheck “Also delete from attachment storage”
2. Delete from chat only

Maximum attachment limit reached

Error: Cannot attach more files to a messageCause: Attempting to attach more than the maximum number of files per message (default: 10)Solution:

1. Remove some attachments to stay within the limit
2. Send multiple messages if needed
3. Combine related content into fewer files when possible

Maximum image attachment limit reached

Error: Toast warning — Maximum N image attachments allowedCause: The number of non-SVG images attached would exceed the image attachment limit (default: 10). SVG files do not count toward this limit because they are processed as documents.Solution:

1. Remove some image attachments
2. Send images across multiple messages

Total message size exceeds limit

Error: Message fails to send due to total attachment sizeCause: Combined size of all attachments exceeds 150 MBSolution:

1. Reduce number of attachments
2. Compress images or files
3. Send multiple messages with fewer attachments each

---