Working with Documents in AI Agents

Giving your AI agents the ability to read, understand, and act on information from documents is one of the most powerful capabilities you can configure. The document strategy you choose directly affects your AI agent's accuracy, speed, and AI action consumption.

This page explains how AI agents work with documents, the available document tools, and how to choose the right approach for your use case.

Understanding document tools

AI agents have access to multiple document processing strategies. When you configure a document input or add a document tool to your AI agent, the AI agent can automatically select from system document tools and the DocCenter tool based on your instructions:

• Semantic Search: Finds specific information within documents by searching for relevant content.
• Read Full Document: Loads the entire document into the AI agent's context for deep reasoning.
• Query Document: Executes dynamic prompts against document content for extraction or summarization.
• DocCenter models: Process model tools that invoke DocCenter models for high-accuracy extraction and classification.

Semantic Search tool

Semantic Search finds specific answers within large document collections by intelligently searching for relevant content.

Best for

Use the Semantic Search tool for these scenarios:

• Question-answering and fact-checking across large document sets.
• Knowledge retrieval from documents that exceed the context window.
• High-volume or customer-facing agents where cost efficiency matters.

Key characteristics

The Semantic Search tool has the following characteristics:

• Handles massive scale: thousands of pages across multiple documents.
• Cost-efficient: uses embedding tokens for search, only passing relevant snippets to the reasoning model.
• Indexes documents once: vectorizes and indexes documents at runtime, allowing reuse without re-reading.
• Fast and precise: delivers targeted answers without processing irrelevant content.

Supported document types

Semantic search supports the following text-based document formats:

• DOC (structured and unstructured)
• DOCX
• HTML
• MD
• PDF (not image-based or scanned)
• TXT

Limitations

The Semantic Search tool has the following limitations:

• Documents are indexed at runtime on first use, which may slow initial runs.
• Combined limit of 75 documents and 50 MB total size per agent run.
• Only searches direct child documents in folders; nested folders require separate tools.

Example use case

You're building a corporate helpdesk AI agent to answer employee questions based on 5,000 pages of internal documentation including HR policies, IT guides, and benefits information.

When an employee asks "What is the process for international travel approval?", your AI agent uses the Semantic Search tool to query the entire knowledge base and retrieves the three most relevant paragraphs instantly.

Why not other tools?

The Read Full Document tool can't handle this volume. The Query Document tool isn't designed for open-ended question-answering across multiple documents.

Read Full Document tool

The Read Full Document tool loads the entire text of a document so your AI agent can understand it completely.

Use the Read Full Document tool for these scenarios:

• Analysis that requires understanding how different parts of a document connect.
• Tasks that need a full understanding of tone, argument, or story.
• High-value analysis where the cost is worth the benefit.

The Read Full Document tool has the following characteristics:

• Complete view: Your AI agent understands how different sections relate to each other.
• Deep understanding: Supports complex analysis and comparison tasks.
• Document limits: Up to 20 pages for documents with images, 50 pages for text-only documents.
• Higher cost: Loads the entire document, which uses more AI actions.

How your AI agent selects this tool

Your AI agent is more likely to use the Read Full Document tool when it needs to compare sections, understand document structure, or perform analysis that requires the complete picture. To encourage this behavior, tell your AI agent to read the entire document in your Instructions.

Example use case

You're building a resume screening AI agent to review candidate resumes against your screening policy.

Your AI agent uses the Read Full Document tool to read both the candidate's resume and the screening policy. It can then evaluate whether the candidate meets all qualification criteria by considering the relationships between experience, education, and requirements.

Why not other tools?

The Semantic Search tool might miss important evaluation criteria. The Query Document tool would require multiple steps to capture all the details in the resume and screening criteria.

Query Document tool

The Query Document tool asks specific questions about a document to extract, summarize, or classify information.

Use the Query Document tool for these scenarios:

• Pulling data from documents with different formats.
• Summarization and classification tasks.
• Workflows where flexibility and speed matter more than perfect accuracy.

The Query Document tool has the following characteristics:

• Flexible questions: your AI agent creates questions based on what it needs to find.
• Adapts easily: works with different document formats without setup.
• Efficient: returns clean, organized output instead of raw text.
• No setup required: easy to get started.
• Document limits: up to 100 pages for text, 20 pages for documents with images.

Example use case

You're building a sales order processing AI agent to handle PDF purchase orders from various customers and enter them into your CRM.

When a purchase order arrives, your AI agent uses the Query Document tool to ask "Extract the PO Number, Customer Name, Item SKUs, Quantities, and Total Amount into a JSON object." Your AI agent receives clean JSON and proceeds to update the CRM.

Why not other tools?

The Read Full Document tool would require your AI agent to search through all the text itself, which is less efficient. DocCenter might be more than you need if purchase order formats are fairly consistent and you don't require maximum accuracy.

DocCenter models

DocCenter lets you build models for your specific documents, helping you achieve higher extraction and classification accuracy.

DocCenter workflows can include confidence scores, quality metrics, and reconciliation steps that route documents for human review when extraction results are incomplete or uncertain. This makes DocCenter the preferred approach for regulated, financial, or legally sensitive use cases where human validation is required before downstream processing.

Use DocCenter models for:

• Regulatory, financial, or legally sensitive documents.
• Repeatable, high-stakes tasks where accuracy is critical.

DocCenter models have the following characteristics:

• Near-perfect accuracy: designed for scenarios where errors have serious consequences.
• Specialized: performs better than general-purpose extraction.
• Requires setup: you must create and train DocCenter models, then connect them through process model tools.

How to use DocCenter with AI agents

To use DocCenter models with your AI agent, complete the following steps:

1. Add the process model to your AI agent as a tool.
   • Use AIA Classification Run Model Version for classification.
   • Use AIA Extraction Run Model Version for extraction.
2. In your AI agent's Instructions, tell your AI agent when to use the tool.

Enforcing DocCenter usage inside an AI agent

To ensure predictable, high-accuracy extraction and classification, explicitly instruct your AI agent to route all such requests through your DocCenter process model tool. This prevents the AI agent from attempting extraction with system document tools.

In your AI agent's Instructions, include the following: "Use only the DocCenter tool for document classification or field extraction. Do not attempt extraction using other system document tools like Read Full Document, Semantic Search, or Query Document."

When calling the DocCenter tool, provide the following inputs:

• document: the user-provided document or content reference
• docType: the expected document category if known (for example "invoice", "w2"); otherwise "unknown"
• modelId: for example, "invoice_v3" (change if a different profile is required)

The tool returns the following outputs:

• classification (text)
• fields (key value map with strings/numbers/dates)
• status (success/partial/failed)
• errorMessage (when status != success)

If the tool is unavailable or fails twice, instruct the AI agent to stop and reply with: handoff_required: <one-sentence reason>.

Example use case

You have a mortgage application and are building an AI agent to digitize application packets and extract dozens of fields from forms like the Fannie Mae 1003 with extreme precision for your underwriting system.

Your AI agent receives a 50-page application PDF. It calls the DocCenter tool specifically configured to handle mortgage documents. The tool returns a highly accurate, structured data set of all required fields.

Why not other tools?

The risk of extraction errors with the Query Document tool tool is too high for this use case. Regulatory requirements demand the accuracy that only DocCenter can provide.

How your AI agent chooses document tools

Your AI agent automatically selects the most appropriate tool based on your instructions and the task at hand. By default, AI agents favor the Semantic Search tool because it's more cost-efficient. You can influence this choice. Use your Instructions to guide the selection.

To override this default behavior and force the AI agent to use a specific tool, explicitly instruct it in your Instructions. For example, to ensure the AI agent uses the Read Full Document tool, include instructions like "Read the entire document to understand the full context" or "Load the complete document into your context."

Decision framework

Your need	Tool your AI agent may use	Why
Find specific facts in large document collections	Semantic Search	Cost-efficient, handles scale, precise retrieval
Understand relationships between document sections	Read Full Document	Provides complete view for deep understanding
Extract data from varying document formats	Query Document	Flexible, no setup required
Maximum accuracy for mission-critical extraction	DocCenter	Built specifically for high-stakes scenarios

Cost, speed, and accuracy tradeoffs

Every document tool represents a tradeoff between three factors:

• Cost: AI action usage.
• Speed: How quickly your AI agent can process the document.
• Accuracy: How reliably your AI agent produces correct results.

Semantic Search is often chosen for cost and speed by only passing relevant snippets to your AI agent. This makes it ideal for high-volume scenarios where you need good accuracy at scale.

Read Full Document prioritizes accuracy by giving your AI agent complete context, but uses more AI actions. Your AI agent may choose this tool when the analysis requires understanding the full document.

Query Document balances all three factors, providing good accuracy with moderate cost and speed. It's a flexible option for general-purpose extraction.

DocCenter maximizes accuracy at the expense of setup time and configuration effort. Use this when errors are unacceptable.

Common misconceptions

"If a document fits, the Read Full Document tool is always best."

Not quite. While AI agents can handle long documents, fitting doesn't mean your AI agent will choose the Read Full Document tool. Here's why:

• Cost: The Read Full Document tool uses more AI actions. If your AI agent only needs to find a specific fact, it's more likely to use the Semantic Search tool, which is far more cost-efficient.
• Precision: For finding specific details in large documents, AI agents can overlook information buried deep in the content. The Semantic Search tool is more reliable for finding specific information.
• Task alignment: If your goal is data extraction, your AI agent is more likely to use the Query Document tool or DocCenter tools, which are built for this task and more efficient than loading the full document.

Best practices

Follow these guidelines to help your AI agent choose the right document tools:

• Write clear Instructions that describe your task. Your AI agent will often choose the Semantic Search tool for most document-based tasks since it's cost-efficient and handles the majority of use cases well.
• Be explicit in your instructions when you want your AI agent to use the Read Full Document tool. Include phrases like "read the entire document" or "consider the full context" in your Instructions.
• Describe extraction tasks clearly so your AI agent knows when to use the Query Document tool for flexibility without the setup overhead of DocCenter models.
• Use DocCenter tools for mission-critical scenarios where accuracy requirements exceed 95%. Add these as tools and specify when to use them in your Instructions.
• Test with representative documents to see which tools your AI agent chooses and adjust your instructions if needed.
• Monitor AI action usage in the Monitor tab to understand the cost implications of your AI agent's document tool choices.

Related resources

For more information about working with documents in AI agents:

• For document tool limitations and technical details, see AI Agent Reference.
• For guidance on creating DocCenter models, see the DocCenter documentation.
• For testing your document processing, see Monitor AI Agents.
• For troubleshooting document issues, see Troubleshooting AI Agents.

Feedback