Files

Files are how you give your agents access to knowledge. Upload documents, organize them into collections, and control which agents can search and reference them.

​

Collections

Documents are organized into collections — folders that group related content together. For example, you might have collections for “Product Documentation”, “Company Policies”, or “API Reference”. Each collection can be configured to restrict access to specific agents, or left open for all agents to search.

​

Documents

​

Uploading Documents

Click Upload Files in a collection to add files. Supported formats: You can also create documents directly from text using the Create File button — useful for pasting in policies, instructions, or any text content.

​

Processing Pipeline

When a document is uploaded or created, it goes through an automatic processing pipeline:

1. Extracting — text content is extracted from the file
2. Chunking — content is split into semantic chunks
3. Embedding — chunks are converted to vector embeddings for search

The document status shows where it is in this pipeline. Once processing completes, the document is available for agent search.

​

How Agents Use Documents

Agents automatically search your files using the search_knowledge tool when they need information. This uses semantic similarity (vector search) to find relevant chunks across all collections the agent has access to. No configuration is needed to enable search — if a document is in a collection the agent can access, it’s searchable.

​

Bookmarks

Bookmarks let you pin specific documents so they appear directly in an agent’s system prompt. This is useful for content the agent should always be aware of, rather than discovering through search.

​

How Bookmarks Work

When you bookmark a document for an agent:

1. The document’s title and usage description appear in the agent’s system prompt
2. The agent uses the read_document tool to access the full content when needed
3. The agent knows the document exists and what it’s for, without loading the full content into every request

​

When to Use Bookmarks

Bookmarks are ideal for:

• Instructions and SOPs — step-by-step procedures the agent should follow
• Policies — refund policies, escalation rules, compliance guidelines
• Reference material — pricing tables, product specs, FAQ documents
• Templates — response templates the agent should use in specific situations

​

Bookmark Modes

Each document can be bookmarked with one of three modes: When bookmarking, you provide a usage description that tells the agent when and how to use the document. This description appears in the system prompt alongside the document title.

​

Collection Agent Access

By default, all agents can search all collections. You can restrict a collection to specific agents if you want to limit which agents can find its documents through search. This is separate from bookmarks — a bookmarked document is always available to the agents it’s bookmarked for, regardless of collection access settings.

​

Code Execution

Every agent has access to execute_code, a tool that runs Python in a restricted sandbox. This is useful for calling external APIs via allowed domains, processing data, and performing calculations. The sandbox:

• Has no import — standard library modules are not available
• Uses data = await fetch(url) for HTTP GET requests to allowed domains
• Requires assigning a JSON-serializable value to result
• Has access to a context dict with organization_id, agent_id, and run_id
• Automatically injects authentication headers configured on allowed domains

Bookmarked documents are ideal for giving agents detailed instructions on how to use execute_code for specific tasks (e.g., “Use execute_code to look up orders from our API”).

​

Best Practices