File search tool for Microsoft Foundry agents

Configure the file search tool for Microsoft Foundry agents. Upload files, create vector stores, and query documents with Python, C#, and REST examples.

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.

File search has additional charges beyond the token-based fees for model usage.

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:

1. Rewrites your query to optimize it for search.
2. Breaks down complex queries into parallel searches.
3. Runs hybrid search combining keyword and semantic matching across vector stores.
4. 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

• Azure AI Search tool - Search existing Azure AI Search indexes from your agents
• Web search tool - Enable agents to search the public web
• Vector stores for file search - Understand vector store lifecycle and expiration
• Structured inputs - Parameterize agent definitions at runtime