/microsoft-foundry

Tool — File Search (type: file_search)

Vector-store-backed retrieval over uploaded files — a connectionless built-in (the vector store is referenced by the toolbox tool). Use the flat tool shape: vector_store_ids is a sibling of type, not nested under file_search. For the toolbox concept, versions, and endpoint, see toolbox.md.

🚦 Before creating a toolbox/connection either way, read create-hosted.md → Toolbox creation boundary.

Prerequisite — create a vector store

File search needs a vector store populated with your files. Create it via the project's OpenAI-compatible endpoints ({project}/openai/v1/...), using a token scoped to https://ai.azure.com/.default. Requires Storage Blob Data Contributor on the project storage and Foundry User/Owner on the project.

PROJ="$FOUNDRY_PROJECT_ENDPOINT"
TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

# 1. Upload a file (purpose=assistants)
FILE_ID=$(curl -sS -X POST "$PROJ/openai/v1/files" -H "Authorization: Bearer $TOKEN" \
  -F purpose="assistants" -F file="@./mydoc.txt" | jq -r .id)

# 2. Create a vector store with that file
VS_ID=$(curl -sS -X POST "$PROJ/openai/v1/vector_stores" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d "{\"name\":\"my-vs\",\"file_ids\":[\"$FILE_ID\"]}" | jq -r .id)

# 3. Poll until ingestion completes (status must be 'completed' before use)
curl -sS "$PROJ/openai/v1/vector_stores/$VS_ID" -H "Authorization: Bearer $TOKEN" | jq '.status, .file_counts'

Use the resulting VS_ID (form vs_...) below. One vector store per agent; up to 10,000 files per store; 512 MB per file.

A. Imperative CLI

Steps 1–3 of toolbox.md § The flow — connectionless, so it goes under a tools: block. Write the toolbox spec to a file — azd ai toolbox create --from-file takes a path (stdin - is not supported).

# 0. Install the CLI extension (once)
azd extension install azure.ai.toolboxes

# Write the toolbox spec to a file (use the real VS_ID from the prerequisite)
cat > fs.yaml <<EOF
description: file-search toolbox
tools:
  - type: file_search
    vector_store_ids: ["$VS_ID"]   # flat: sibling of type, NOT nested under file_search
EOF

Create a new toolbox (first version auto-promoted):

azd ai toolbox create agent-tools --from-file fs.yaml --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT"

Add to an existing toolbox: the current azd CLI does not support adding a connectionless built-in to an existing toolbox — you can only create a new toolbox (azd ai toolbox create) with the full tool set.

--from-file entry:

tools:
  - type: file_search
    vector_store_ids: ["vs_..."]

B. Declarative azure.yaml

Declare the toolbox as a host: azure.ai.toolbox service in azure.yaml; azd deploy upserts it (and auto-promotes the new version). Needs only an existing Foundry project (via FOUNDRY_PROJECT_ENDPOINT + AZURE_SUBSCRIPTION_ID in the azd env) — no azd provision, no infra: block.

name: my-agent-project
services:
  agent-tools:
    host: azure.ai.toolbox
    tools:
      - type: file_search
        vector_store_ids: ["vs_..."]   # flat shape

  # A hosted agent in the same project consumes the toolbox by name
  my-agent:
    host: azure.ai.agent
    uses:
      - agent-tools
    environmentVariables:
      - name: TOOLBOX_NAME
        value: agent-tools

azd deploy agent-tools

Verify & deploy

After creating the toolbox either way, verify its MCP endpoint end-to-end — see test-endpoint.md.

References

• File Search tool documentation — vector store creation, SDK/REST samples
• Vector stores for file search
• toolbox.md § Supported tool types