Use the file search tool to enable Microsoft Foundry agents to search through your documents and retrieve relevant information. File search augments agents with knowledge from outside the Foundry model powering the agent, such as proprietary product information or user-provided documents.
In this article, you learn how to:
- Upload files and create a vector store
- Configure an agent with file search enabled
- Query your documents through the agent
By using the standard agent setup, the improved file search tool ensures your files remain in your own storage. Your Azure AI Search resource ingests the files, so you maintain complete control over your data.
Usage support
The following table shows SDK and setup support.
| Microsoft Foundry support | Python SDK | C# SDK | JavaScript SDK | Java SDK | REST API | Basic agent setup | Standard agent setup |
|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Prerequisites
- A basic or standard agent environment
- The SDK package for your language:
- Python:
azure-ai-projects (latest)
- .NET:
Azure.AI.Extensions.OpenAI
- TypeScript:
@azure/ai-projects (latest)
- Java:
azure-ai-agents
- Storage Blob Data Contributor role on your project’s storage account (required for uploading files to your project’s storage)
- Foundry Owner role on your Foundry resource (required for creating agent resources)
The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.
- Azure credentials configured for authentication (such as
DefaultAzureCredential).
- Your Foundry project endpoint URL and model deployment name.
Code examples
The following examples show how to upload a file, create a vector store, configure an agent with file search enabled, and query the agent.
You can customize file search behavior at runtime, such as specifying which vector store to use per request, by using structured inputs. Verify file search results
After running a code sample in this article, verify that file search is working:
- Confirm that the vector store and file are created.
- In the Python and TypeScript samples, the upload-and-poll helpers complete only after ingestion finishes.
- Ask a question that you can answer only from your uploaded content.
- Confirm that the response is grounded in your documents.
File sources
- Upload local files (Basic and Standard agent setup)
- Azure Blob Storage (Standard setup only)
File search behavior by agent setup type
Basic agent setup
The file search tool has the same functionality as Azure OpenAI Responses API. The tool uses Microsoft managed search and storage resources.
- You store uploaded files in Microsoft managed storage.
- You create a vector store by using a Microsoft managed search resource.
Standard agent setup
The file search tool uses the Azure AI Search and Azure Blob Storage resources you connect to during agent setup.
- You store uploaded files in your connected Azure Blob Storage account.
- You create vector stores by using your connected Azure AI Search resource.
For both agent setups, the service handles the entire ingestion process, which includes:
- Automatically parsing and chunking documents.
- Generating and storing embeddings.
- Utilizing both vector and keyword searches to retrieve relevant content for user queries.
The code is identical for both setups. The only variation is where your files and vector stores are stored.
When to use file search
Choose file search when you need to:
- Search through documents you upload directly (PDFs, Word docs, code files)
- Enable agents to answer questions from proprietary or confidential content
- Process files up to 512 MB without managing external search infrastructure
Consider alternatives for these scenarios:
| Scenario | Recommended tool |
|---|
| Search existing Azure AI Search indexes | Azure AI Search tool |
| Search the public web for current information | Web search tool |
| Combine multiple data sources in one query | Use multiple tools together |
How file search works
The file search tool uses retrieval best practices to extract relevant data from your files and improve model responses.
Query processing
When you send a query, file search:
- Rewrites your query to optimize it for search.
- Breaks down complex queries into parallel searches.
- Runs hybrid search combining keyword and semantic matching across vector stores.
- Reranks results to select the most relevant content for the response.
Default chunking settings
| Setting | Default value |
|---|
| Chunk size | 800 tokens |
| Chunk overlap | 400 tokens |
| Embedding model | text-embedding-3-large (256 dimensions) |
| Max chunks in context | 20 |
Vector stores
Vector store objects give the file search tool the ability to search your files. When you add a file to a vector store, the process automatically parses, chunks, embeds, and stores the file in a vector database that supports both keyword and semantic search. Each vector store can hold up to 10,000 files. You can attach vector stores to both agents and conversations. Currently, you can attach at most one vector store to an agent and at most one vector store to a conversation.
For background concepts and lifecycle guidance (readiness, deletion behavior, and expiration policies), see Vector stores for file search.
Remove files from a vector store by:
- Deleting the vector store file object.
- Deleting the underlying file object. This action removes the file from all
vector_store and code_interpreter configurations across all agents and conversations in your organization.
The maximum file size is 512 MB. Each file should contain no more than 5,000,000 tokens (computed automatically when you attach a file).
Ensuring vector store readiness before creating runs
Ensure the system fully processes all files in a vector store before you create a run. This ensures all data in your vector store is searchable. Check for vector store readiness by using the polling helpers in the SDKs, or by manually polling the vector store object to ensure the status is completed.
As a fallback, the run object includes a 60-second maximum wait when the conversation’s vector store contains files that are still processing. This wait ensures that any files your users upload in a conversation are fully searchable before the run proceeds. This fallback wait doesn’t apply to the agent’s vector store.
Conversation vector stores have default expiration policies
Vector stores that you create by using conversation helpers (like tool_resources.file_search.vector_stores in conversations or message.attachments in Messages) have a default expiration policy of seven days after they were last active (defined as the last time the vector store was part of a run).
When a vector store expires, the runs on that conversation fail. To fix this problem, recreate a new vector store with the same files and reattach it to the conversation.
Supported file types
For text MIME types, the encoding must be UTF-8, UTF-16, or ASCII.
| File format | MIME Type |
|---|
.c | text/x-c |
.cs | text/x-csharp |
.cpp | text/x-c++ |
.doc | application/msword |
.docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
.html | text/html |
.java | text/x-java |
.json | application/json |
.md | text/markdown |
.pdf | application/pdf |
.php | text/x-php |
.pptx | application/vnd.openxmlformats-officedocument.presentationml.presentation |
.py | text/x-python |
.py | text/x-script.python |
.rb | text/x-ruby |
.tex | text/x-tex |
.txt | text/plain |
.css | text/css |
.js | text/javascript |
.sh | application/x-sh |
.ts | application/typescript |
Limitations
Keep these limits in mind when you plan your file search integration:
- File search supports specific file formats and encodings. See Supported file types.
- Each vector store can hold up to 10,000 files.
- You can attach at most one vector store to an agent and at most one vector store to a conversation.
- Features and availability vary by region. See Azure AI Foundry region support.
Troubleshooting
| Issue | Likely cause | Resolution |
|---|
| 401 Unauthorized | The access token is missing, expired, or scoped incorrectly. | Get a fresh token and retry the request. For REST calls, confirm you set AGENT_TOKEN correctly. |
| 403 Forbidden | The signed-in identity doesn’t have the required roles. | Confirm the roles in Prerequisites and retry after role assignment finishes propagating. |
| 404 Not Found | The project endpoint or resource identifiers are incorrect. | Confirm FOUNDRY_PROJECT_ENDPOINT and IDs such as agent name, version, vector store ID, and file ID. |
| Responses ignore your files | The agent isn’t configured with file_search, or the vector store isn’t attached. | Confirm the agent definition includes file_search and the vector_store_ids list contains your vector store ID. |
| File upload times out | Large file or slow network connection. | Use upload_and_poll to handle large files. Consider chunking very large documents. |
| Vector store creation fails | Quota exceeded or invalid file format. | Check vector store limits (10,000 files per store). Verify file format is supported. |
| Search returns irrelevant results | File content not properly indexed or query too broad. | Wait for indexing to complete (check vector_store.status). Use more specific queries. |
| No citations in response | Model didn’t use file search or content not found. | Use tool_choice="required" to force file search. Verify the file content matches your query topic. |
Related content