Ferramenta de pesquisa de arquivos para agentes

Use a ferramenta de busca de arquivos para basear os agentes do Microsoft Foundry nos seus próprios dados. Com a pesquisa de arquivos, os agentes podem recuperar informações relevantes de seus documentos e usá-los para gerar respostas mais precisas e com reconhecimento de contexto, aumentando agentes com conhecimento, como informações proprietárias do produto ou documentos fornecidos pelo usuário.

Neste artigo, você aprenderá a:

  • Carregar arquivos e criar um repositório de vetores
  • Configurar um agente com a pesquisa de arquivos habilitada
  • Consultar seus documentos por meio do agente

Usando a configuração do agente padrão, a ferramenta de pesquisa de arquivos garante que seus arquivos permaneçam em seu próprio armazenamento. Seu recurso de Pesquisa de IA do Azure  ingere os arquivos, portanto, você mantém controle total sobre seus dados.

Importante

Pesquisa de arquivo tem encargos adicionais além das taxas baseadas em token para uso do modelo.

Pré-requisitos

  • Um ambiente de agente básico ou padrão

  • O pacote do SDK para seu idioma:

    • Python: azure-ai-projects (mais recente)
    • .NET:Azure.AI.Extensions.OpenAI
    • TypeScript: @azure/ai-projects (mais recente)
    • Java:azure-ai-agents

  • Função de Colaborador de dados de blob de armazenamento na conta de armazenamento do seu projeto (necessária para o upload de arquivos no armazenamento do projeto)

  • Função de Usuário do Foundry no projeto Foundry para criar e executar agentes.

    Importante

    As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

  • Azure credenciais configuradas para autenticação (como DefaultAzureCredential).

  • URL do ponto de extremidade do seu projeto Foundry e nome da implantação de modelo.

Carregar e consultar um arquivo

Para obter a forma mais rápida de chegar a uma resposta fundamentada, conclua estas ações na seguinte ordem:

  1. Crie ou selecione um arquivo que contenha um fato que você pode testar.
  2. Carregue o arquivo e adicione-o a um repositório de vetores.
  3. Aguarde até que a ingestão seja concluída.
  4. Anexe a pesquisa de arquivo a um agente e faça uma pergunta que somente o arquivo pode responder.
  5. Verifique se a resposta usa o conteúdo carregado e exclua os recursos que você criou.

Os exemplos Python e TypeScript mostram o fluxo de upload e consulta em um programa. Os requisitos de limpeza variam de acordo com o exemplo, portanto, siga as instruções de limpeza na seção de idioma selecionada.

Suporte ao uso

A tabela a seguir mostra o SDK e o suporte à instalação.

Suporte ao Microsoft Foundry SDK do Python C# SDK SDK para JavaScript SDK do Java API REST Configuração básica do agente Configuração do agente padrão
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Exemplos de código

Os exemplos a seguir mostram como carregar um arquivo, criar um repositório de vetores, configurar um agente com a pesquisa de arquivos habilitada e consultar o agente.

Prepare sua amostra

  • C#hospedado: instalar Microsoft.Agents.AI.Foundry.Hosting e usar AddFoundryToolboxes. Consulte o exemplo do kit de ferramentas hospedado e mantido.
  • REST: use um shell compatível com o Bash com CLI do Azure, Azure Developer CLI e curl. Defina FOUNDRY_PROJECT_ENDPOINT e FOUNDRY_MODEL_DEPLOYMENT_NAME, obtenha um AGENT_TOKEN, e capture o arquivo retornado, o repositório de vetores e as IDs de versão da caixa de ferramentas. As solicitações da caixa de ferramentas permanecem autenticadas com o token de portador.
  • Java: instale o JDK 17 ou posterior e o Maven 3.8 ou posterior. Antes de executar o código Java, use outro exemplo de idioma, REST ou o portal do Foundry para carregar o arquivo, criar o repositório de vetores e a caixa de ferramentas e criar a conexão de projeto de ferramenta remota. Para obter exemplos mantidos do cliente Java, consulte os exemplos do SDK do Java do Azure AI Agents.

Dica

Você pode personalizar o comportamento de pesquisa de arquivos em runtime, como especificar qual repositório de vetores usar por solicitação usando entradas estruturadas.

Criar um agente com a ferramenta de pesquisa de arquivos

O exemplo de código a seguir mostra como adicionar a ferramenta de pesquisa de arquivos a uma caixa de ferramentas e anexar a caixa de ferramentas a um agente. Você precisa carregar arquivos e criar um repositório de vetores antes de executar esse código. Selecione Prompt Agents para usar o SDK de Projetos de IA Azure para criar um agente de prompt do lado do servidor ou Hosted Agents para usar o Agent Framework FoundryChatClient para criar um agente efêmero em processo.

Agentes de prompt

from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import FileSearchTool, PromptAgentDefinition
from azure.identity import DefaultAzureCredential

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Load the file to be indexed for search.
asset_file_path = (Path(__file__).parent / "../assets/product_info.md").resolve()

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
# The openai client uses {PROJECT_ENDPOINT}/openai/v1 for file and vector store operations

# Create vector store and upload file
vector_store = openai.vector_stores.create(name="ProductInfoStore")

with asset_file_path.open("rb") as file_handle:
    vector_store_file = openai.vector_stores.files.upload_and_poll(
        vector_store_id=vector_store.id,
        file=file_handle,
    )

# Create agent with file search tool
agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions=(
            "You are a helpful agent that can search through product information. "
            "Use file search to answer questions from the uploaded files."
        ),
        tools=[FileSearchTool(vector_store_ids=[vector_store.id])],
    ),
    description="File search agent for product information queries.",
)

# Create conversation and generate response
conversation = openai.conversations.create()

response = openai.responses.create(
    conversation=conversation.id,
    input="Tell me about Contoso products",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

# Clean up resources
project.agents.delete_version(
    agent_name=agent.name,
    agent_version=agent.version,
)
openai.vector_stores.delete(vector_store.id)

Saída esperada

A saída a seguir vem do exemplo de código anterior:

[Response text grounded in your uploaded document content]

Referências

Agentes hospedados

Este exemplo cria a toolbox de pesquisa de arquivos com o SDK do Azure AI Projects, depois usa FoundryChatClient do Microsoft Agent Framework e se conecta ao endpoint MCP da toolbox usando FoundryToolbox. Defina as variáveis de ambiente FOUNDRY_PROJECT_ENDPOINT e FOUNDRY_MODEL e faça login usando az login.

import asyncio
from pathlib import Path

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import FileSearchToolboxTool
from azure.identity import AzureCliCredential

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"

async def main() -> None:
    credential = AzureCliCredential()

    # Load the file to be indexed for search.
    asset_file_path = (Path(__file__).parent / "../assets/product_info.md").resolve()

    # Create vector store and upload file.
    project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=credential)
    openai = project.get_openai_client()
    vector_store = openai.vector_stores.create(name="ProductInfoStore")

    with asset_file_path.open("rb") as file_handle:
        vector_store_file = openai.vector_stores.files.upload_and_poll(
            vector_store_id=vector_store.id,
            file=file_handle,
        )

    # 1. Add the file search tool to a toolbox. Using a toolbox is the recommended way
    #    to give agents tools: you curate tools once and reuse the toolbox across agents.
    #    See /azure/foundry/agents/concepts/toolbox-overview
    toolbox = project.toolboxes.create_version(
        name="file-search-toolbox",
        description="Toolbox with the file search tool",
        tools=[FileSearchToolboxTool(vector_store_ids=[vector_store.id])],
    )

    # 2. The toolbox exposes an MCP-compatible endpoint.
    TOOLBOX_MCP_URL = (
        f"{PROJECT_ENDPOINT}/toolboxes/{toolbox.name}"
        f"/versions/{toolbox.version}/mcp?api-version=v1"
    )

    # 3. Attach the toolbox to the hosted agent as an MCP tool.
,
        timeout=120.0,
    )
    toolbox_tool = FoundryToolbox(credential, url=TOOLBOX_MCP_URL)

agent = Agent(
        client=FoundryChatClient(credential=credential),
        instructions="You are a helpful assistant that can search through files to find information.",
        tools=[toolbox_tool],
    )

    result = await agent.run("What is the weather today? Do a file search to find the answer.")
    print(f"Agent: {result.text}")

if __name__ == "__main__":
    asyncio.run(main())

Saída esperada

O agente busca no conteúdo indexado dos arquivos no banco de vetores e retorna uma resposta fundamentada. A saída do console mostra o texto de resposta final que contém a resposta derivada do arquivo carregado.

Agent: The weather today is sunny with a high of 75F.

Para obter o exemplo completo, consulte foundry_chat_client_with_file_search.py.

Exemplo de pesquisa de arquivo com o agente

Neste exemplo, você cria um arquivo local, carrega-o em Azure e o usa no VectorStore recém-criado para pesquisa de arquivos. Selecione Prompt Agents para usar o SDK de Projetos de IA Azure para criar um agente de prompt do lado do servidor ou Hosted Agents para usar o Microsoft Agent Framework para criar um agente efêmero em processo.

Agentes de prompt

O código neste exemplo é síncrono e streaming. Para uso assíncrono, consulte o código sample no SDK do Azure para .NET repositório em GitHub.

using System;
using System.IO;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using OpenAI.Files;
using OpenAI.VectorStores;

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";

// Create project client to call Foundry API
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

// Create a toy example file and upload it using OpenAI mechanism.
string filePath = "sample_file_for_upload.txt";
File.WriteAllText(
    path: filePath,
    contents: "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.");
OpenAIFileClient fileClient = projectClient.ProjectOpenAIClient.GetOpenAIFileClient();
OpenAIFile uploadedFile = fileClient.UploadFile(filePath: filePath, purpose: FileUploadPurpose.Assistants);
File.Delete(filePath);

// Create the VectorStore and provide it with uploaded file ID.
VectorStoreClient vctStoreClient = projectClient.ProjectOpenAIClient.GetVectorStoreClient();
VectorStoreCreationOptions options = new()
{
    Name = "MySampleStore",
    FileIds = { uploadedFile.Id }
};
VectorStore vectorStore = vctStoreClient.CreateVectorStore(options: options);

// Create an Agent capable of using File search.
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful agent that can help fetch data from files you know about.",
    Tools = { ResponseTool.CreateFileSearchTool(vectorStoreIds: new[] { vectorStore.Id }), }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// Ask a question about the file's contents.
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);

ResponseResult response = responseClient.CreateResponse("Can you give me the documented codes for 'banana' and 'orange'?");

Console.WriteLine(response.GetOutputText());

// Remove all the resources created in this sample.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
vctStoreClient.DeleteVectorStore(vectorStoreId: vectorStore.Id);
fileClient.DeleteFile(uploadedFile.Id);

Saída esperada

A saída a seguir vem do exemplo de código anterior:

The code for 'banana' is 673457. I couldn't find any documented code for 'orange' in the files I have access to.

Agentes hospedados

O código a seguir é um fragmento de integração. Ele cria a caixa de ferramentas de pesquisa de arquivos com o SDK de projetos de IA Azure e, em seguida, usa a integração do Microsoft Agent FrameworkAddFoundryToolboxes. Para obter os pacotes necessários, as importações e a implementação do auxiliar mantido, consulte Conectar um agente hospedado a uma caixa de ferramentas e ao exemplo de caixa de ferramentas hospedada pública. Defina as variáveis de ambiente AZURE_AI_PROJECT_ENDPOINT, AZURE_OPENAI_ENDPOINT e AZURE_AI_MODEL_DEPLOYMENT_NAME e faça login com az login.

Fragmento de integração dependente do auxiliar:

using System;
using System.IO;
using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.AI;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;
using OpenAI.Files;
using OpenAI.VectorStores;

const string AgentInstructions = "You are a helpful assistant that can search through uploaded files to answer questions.";
const string AgentName = "FileSearchAgent";

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? "https://<account>.services.ai.azure.com/api/projects/<project>";
string openAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";

DefaultAzureCredential credential = new();

// 1. Create the file search tool and add it to a toolbox. Using a toolbox is the
//    recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);

// Create a toy example file and upload it using OpenAI mechanism.
string filePath = "sample_file_for_upload.txt";
File.WriteAllText(
    path: filePath,
    contents: "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.");
OpenAIFileClient fileClient = projectClient.ProjectOpenAIClient.GetOpenAIFileClient();
OpenAIFile uploadedFile = fileClient.UploadFile(filePath: filePath, purpose: FileUploadPurpose.Assistants);
File.Delete(filePath);

// Create the VectorStore and provide it with uploaded file ID.
VectorStoreClient vctStoreClient = projectClient.ProjectOpenAIClient.GetVectorStoreClient();
VectorStoreCreationOptions options = new()
{
    Name = "MySampleStore",
    FileIds = { uploadedFile.Id }
};
VectorStore vectorStore = vctStoreClient.CreateVectorStore(options: options);

ProjectsAgentTool fileSearchTool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateFileSearchTool(vectorStoreIds: new[] { vectorStore.Id }));

ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "file-search-toolbox",
        tools: [fileSearchTool],
        description: "Toolbox with the file search tool");

// Create the hosted agent and register the toolbox integration.
AIAgent agent = projectClient.AsAIAgent(
    model: deploymentName,
    instructions: "You are a helpful assistant with access to the toolbox tools.",
    name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxVersion.Name);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Saída esperada

O agente hospedado usa o endpoint MCP do toolbox para pesquisar o repositório vetorial configurado no toolbox de pesquisa de arquivos e responde com conteúdo fundamentado.

Response: The youngest employee is Alice Johnson, who is 28 years old.
File Citation - File Id: file-abc123

Para obter uma integração mantida do .NET Agent Framework, consulte Usar uma caixa de ferramentas com um agente hospedado.

Exemplo de pesquisa de arquivos com um agente em cenários de streaming

Neste exemplo, você cria um arquivo local, carrega-o em Azure e o usa no VectorStore recém-criado para pesquisa de arquivos. O código neste exemplo é síncrono e streaming. Para uso assíncrono, consulte o código sample no SDK do Azure para .NET repositório em GitHub.

using System;
using System.IO;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using OpenAI.Files;
using OpenAI.VectorStores;

class FileSearchStreamingDemo
{
    // Create a helper method ParseResponse to format streaming response output.
    // If the stream ends up in error state, it will throw an error. 
    private static void ParseResponse(StreamingResponseUpdate streamResponse)
    {
        if (streamResponse is StreamingResponseCreatedUpdate createUpdate)
        {
            Console.WriteLine($"Stream response created with ID: {createUpdate.Response.Id}");
        }
        else if (streamResponse is StreamingResponseOutputTextDeltaUpdate textDelta)
        {
            Console.WriteLine($"Delta: {textDelta.Delta}");
        }
        else if (streamResponse is StreamingResponseOutputTextDoneUpdate textDoneUpdate)
        {
            Console.WriteLine($"Response done with full message: {textDoneUpdate.Text}");
        }
        else if (streamResponse is StreamingResponseOutputItemDoneUpdate itemDoneUpdate)
        {
            if (itemDoneUpdate.Item is MessageResponseItem messageItem)
            {
                foreach (ResponseContentPart part in messageItem.Content)
                {
                    foreach (ResponseMessageAnnotation annotation in part.OutputTextAnnotations)
                    {
                        if (annotation is FileCitationMessageAnnotation fileAnnotation)
                        {
                            // Note fileAnnotation.Filename will be available in OpenAI package versions
                            // greater then 2.6.0.
                            Console.WriteLine($"File Citation - File ID: {fileAnnotation.FileId}");
                        }
                    }
                }
            }
        }
        else if (streamResponse is StreamingResponseErrorUpdate errorUpdate)
        {
            throw new InvalidOperationException($"The stream has failed with the error: {errorUpdate.Message}");
        }
    }
    public static void Main()
    {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        var projectEndpoint = "your_project_endpoint";

        // Create project client to call Foundry API
        AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

        // Create a toy example file and upload it using OpenAI mechanism.
        string filePath = "sample_file_for_upload.txt";
        File.WriteAllText(
            path: filePath,
            contents: "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.");
        OpenAIFile uploadedFile = projectClient.ProjectOpenAIClient.GetProjectFilesClient().UploadFile(filePath: filePath, purpose: FileUploadPurpose.Assistants);
        File.Delete(filePath);

        // Create the `VectorStore` and provide it with uploaded file ID.
        VectorStoreCreationOptions options = new()
        {
            Name = "MySampleStore",
            FileIds = { uploadedFile.Id }
        };
        VectorStore vectorStore = projectClient.ProjectOpenAIClient.GetProjectVectorStoresClient().CreateVectorStore(options);

        // 1. Add the file search tool to a toolbox. Using a toolbox is the recommended
        //    way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
        AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

        ProjectsAgentTool fileSearchTool = ProjectsAgentTool.AsProjectTool(
            ResponseTool.CreateFileSearchTool(vectorStoreIds: new[] { vectorStore.Id }));

        ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
            .GetAgentToolboxes().CreateToolboxVersion(
                toolboxName: "file-search-toolbox",
                tools: [fileSearchTool],
                description: "Toolbox with the file search tool");

        // 2. The toolbox exposes an MCP-compatible endpoint.
        var toolboxMcpUrl = new Uri(
            $"{projectEndpoint}/toolboxes/{toolboxVersion.Name}" +
            $"/versions/{toolboxVersion.Version}/mcp?api-version=v1");

        // 3. Create a remote-tool project connection that points at the toolbox endpoint.
        //    Use a user Entra token so the caller's identity is passed through
        //    (audience https://ai.azure.com). Create the connection once, for example
        //    with the Azure Developer CLI:
        //
        //    azd ai connection create file-search-toolbox-conn \
        //      --kind remote-tool \
        //      --target "<toolboxMcpUrl>" \
        //      --auth-type user-entra-token \
        //      --audience https://ai.azure.com
        var toolboxConnectionName = "file-search-toolbox-conn";

        // 4. Attach the toolbox to the prompt agent as an MCP tool.
        McpTool toolboxTool = ResponseTool.CreateMcpTool(
            serverLabel: "toolbox",
            serverUri: toolboxMcpUrl,
            toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
                GlobalMcpToolCallApprovalPolicy.NeverRequireApproval));
        toolboxTool.ProjectConnectionId = toolboxConnectionName;

        DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
        {
            Instructions = "You are a helpful agent that can help fetch data from files you know about.",
            Tools = { toolboxTool }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition)
        );

        // Create the conversation to store responses.
        ProjectConversation conversation = projectClient.ProjectOpenAIClient.GetProjectConversationsClient().CreateProjectConversation();
        CreateResponseOptions responseOptions = new()
        {
            Agent = agentVersion,
            AgentConversationId = conversation.Id,
            StreamingEnabled = true,
        };
        // Wait for the stream to complete.
        responseOptions.InputItems.Clear();
        responseOptions.InputItems.Add(ResponseItem.CreateUserMessageItem("Can you give me the documented codes for 'banana' and 'orange'?"));
        foreach (StreamingResponseUpdate streamResponse in projectClient.ProjectOpenAIClient.Responses.CreateResponseStreaming(responseOptions))
        {
            ParseResponse(streamResponse);
        }

        // Ask follow up question and start a new stream.
        Console.WriteLine("Demonstrating follow-up query with streaming...");
        responseOptions.InputItems.Clear();
        responseOptions.InputItems.Add(ResponseItem.CreateUserMessageItem("What was my previous question about?"));
        foreach (StreamingResponseUpdate streamResponse in projectClient.ProjectOpenAIClient.Responses.CreateResponseStreaming(responseOptions))
        {
            ParseResponse(streamResponse);
        }

        // Remove all the resources created in this sample.
        projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
        projectClient.ProjectOpenAIClient.GetProjectVectorStoresClient().DeleteVectorStore(vectorStoreId: vectorStore.Id);
        projectClient.ProjectOpenAIClient.GetProjectFilesClient().DeleteFile(uploadedFile.Id);
    }
}

Saída esperada

A saída a seguir vem do exemplo de código anterior:

Stream response created with ID: <response-id>
Delta: The code for 'banana' is 673457. I couldn't find any documented code for 'orange' in the files I have access to.
Response done with full message: The code for 'banana' is 673457. I couldn't find any documented code for 'orange' in the files I have access to.
File Citation - File ID: <file-id>
Demonstrating follow-up query with streaming...
Stream response created with ID: <response-id>
Delta: Your previous question was about the documented codes for 'banana' and 'orange'.
Response done with full message: Your previous question was about the documented codes for 'banana' and
'orange'.

Pesquisa de arquivo de exemplo com o agente

O exemplo de TypeScript a seguir mostra como adicionar a ferramenta de pesquisa de arquivos a uma caixa de ferramentas e anexar a caixa de ferramentas a um agente. Você precisa carregar arquivos e criar um repositório de vetores antes de executar esse código. Consulte a seção Comportamento de pesquisa de arquivos por tipo de configuração de agente abaixo para obter detalhes. Para obter um exemplo de JavaScript, consulte o código sample no repositório SDK do Azure para JavaScript em GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";
import { fileURLToPath } from "url";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";

export async function main(): Promise<void> {
  // Load the file to be indexed for search
  const __filename = fileURLToPath(import.meta.url);
  const __dirname = path.dirname(__filename);
  const assetFilePath = path.join(__dirname, "../assets/product_info.md");

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  // The openai client uses {PROJECT_ENDPOINT}/openai/v1 for file and vector store operations
  const openai = project.getOpenAIClient();

  // Create vector store and upload file
  const vectorStore = await openai.vectorStores.create({
    name: "ProductInfoStore",
  });

  const fileStream = fs.createReadStream(assetFilePath);
  const file = await openai.vectorStores.files.uploadAndPoll(vectorStore.id, fileStream);

  console.log("Creating a toolbox with the file search tool...");

  // 1. Add the file search tool to a toolbox. Using a toolbox is the recommended
  //    way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
  const toolbox = await project.toolboxes.createVersion(
    "file-search-toolbox",
    [
      {
        type: "file_search",
        file_search: {
          vector_store_ids: [vectorStore.id],
        },
      },
    ],
    { description: "Toolbox with the file search tool" },
  );

  // 2. The toolbox exposes an MCP-compatible endpoint.
  const toolboxMcpUrl =
    `${PROJECT_ENDPOINT}/toolboxes/${toolbox.name}` +
    `/versions/${toolbox.version}/mcp?api-version=v1`;

  // 3. Create a remote-tool project connection that points at the toolbox endpoint.
  //    Use a user Entra token so the caller's identity is passed through
  //    (audience https://ai.azure.com). Create the connection once, for example
  //    with the Azure Developer CLI:
  //
  //    azd ai connection create file-search-toolbox-conn \
  //      --kind remote-tool \
  //      --target "<toolboxMcpUrl>" \
  //      --auth-type user-entra-token \
  //      --audience https://ai.azure.com
  const toolboxConnectionName = "file-search-toolbox-conn";

  // 4. Attach the toolbox to a prompt agent as an MCP tool.
  const agent = await project.agents.createVersion("agent-file-search", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "You are a helpful assistant that can search through product information.",
    tools: [
      {
        type: "mcp",
        server_label: "toolbox",
        server_url: toolboxMcpUrl,
        require_approval: "never",
        project_connection_id: toolboxConnectionName,
      },
    ],
  });

  // Create conversation and generate response
  const conversation = await openai.conversations.create();

  const response = await openai.responses.create(
    {
      conversation: conversation.id,
      input: "Tell me about Contoso products",
    },
    {
      body: { agent_reference: { name: agent.name, type: "agent_reference" } },
    },
  );
  console.log(response.output_text);

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
  await openai.vectorStores.delete(vectorStore.id);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Saída esperada

[Response text grounded in your uploaded document content]

Referências

Usar a pesquisa de arquivo em um agente de Java

Dica

A maioria dos agentes usa uma caixa de ferramentas para adicionar a ferramenta de pesquisa de arquivos e anexar a caixa de ferramentas ao seu agente como uma ferramenta MCP. Se você usar o SDK Java, uma API para criar caixas de ferramentas ainda não estará disponível. Crie uma toolbox usando Python, a API REST, C#, TypeScript ou o portal do Foundry e, em seguida, faça referência ao endpoint MCP no seu agente Java como um McpTool.

Adicione a dependência ao seu pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.2.0</version>
</dependency>

Antes de executar este exemplo, crie um arquivo e uma loja de vetores usando os endpoints REST {projectEndpoint}/openai/v1/files e {projectEndpoint}/openai/v1/vector_stores. Em seguida, crie uma caixa de ferramentas de pesquisa de arquivo fora da banda usando o exemplo de Python, REST, C# ou TypeScript ou o portal do Foundry. Crie a conexão do projeto remote-tool para o ponto de extremidade MCP da caixa de ferramentas antes de anexá-la ao agente Java.

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.McpTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Collections;

public class FileSearchExample {
    public static void main(String[] args) {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";
        String toolboxMcpUrl = projectEndpoint
            + "/toolboxes/file-search-toolbox/versions/1/mcp?api-version=v1";
        String toolboxConnectionName = "file-search-toolbox-conn";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // The Java SDK doesn't yet expose a toolbox creation API. Create the
        // toolbox with Python, REST, C#, TypeScript, or the Foundry portal, then
        // attach its MCP endpoint as an MCP tool.
        McpTool toolboxTool = new McpTool("toolbox")
            .setServerUrl(toolboxMcpUrl)
            .setProjectConnectionId(toolboxConnectionName)
            .setRequireApproval("never");

        // Create agent with the toolbox MCP tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini")
            .setInstructions("You are a helpful assistant that can search through files to answer questions.")
            .setTools(Collections.singletonList(toolboxTool));

        AgentVersionDetails agent = agentsClient.createAgentVersion("file-search-agent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("What information is in the uploaded files?"));

        System.out.println("Response: " + response.output());

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}

Saída esperada

Agent created: file-search-agent (version 1)
Response: [ResponseOutputItem containing file search results ...]

Para mais exemplos, incluindo upload de arquivo e criação de repositório de vetores, consulte os exemplos do Azure AI Agents Java SDK.

Carregar arquivos e adicioná-los a um repositório de vetores

Para acessar seus arquivos, a ferramenta de pesquisa de arquivos usa o objeto de repositório de vetores. Carregue seus arquivos e crie um repositório de vetores. Em seguida, verifique o status do armazenamento até que todos os arquivos estejam fora do estado in_progress para garantir que todo o conteúdo seja totalmente processado. O SDK fornece auxiliares para carregamento e sondagem.

Defina a seguinte variável de ambiente antes de executar os exemplos:

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

Carregar um arquivo

curl --request POST \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/files \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -F purpose="assistants" \
  -F file="@c:\\path_to_file\\sample_file_for_upload.txt"

Criar um repositório de vetores

curl --request POST \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/vector_stores \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_vector_store",
    "file_ids": ["'$FILE_ID'"]
  }'

Adicionar pesquisa de arquivo a uma caixa de ferramentas e criar um agente

A maneira recomendada de adicionar a pesquisa de arquivos é por meio de uma caixa de ferramentas e anexar a caixa de ferramentas ao seu agente como uma ferramenta MCP. Veja o que é uma caixa de ferramentas?

Carregar arquivos para uso de caixa de ferramentas

Para criar um armazenamento de arquivos e vetores para uso com uma caixa de ferramentas, carregue o arquivo no ponto de extremidade Files no nível do recurso com o cabeçalho x-aml-project-id. Use o GUID do projeto de properties.amlWorkspace.internalId.

  1. Carregar seu arquivo: POST {account_endpoint}/openai/v1/files com purpose=assistants e cabeçalho x-aml-project-id: {project-guid}.
  2. Crie um repositório de vetores: POST {account_endpoint}/openai/v1/vector_stores com a ID de arquivo retornada e o mesmo x-aml-project-id cabeçalho.

A ID do repositório de vetor resultante é o valor que você fornece como <VECTOR_STORE_ID>.

  1. Crie uma caixa de ferramentas que contenha a ferramenta de pesquisa de arquivos:

    curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/file-search-toolbox/versions?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "Toolbox with the file search tool",
    "tools": [
      {
        "type": "file_search",
        "file_search": {
          "vector_store_ids": ["'$VECTOR_STORE_ID'"]
        },
        "max_num_results": 20
      }
    ]
  }'

    O kit de ferramentas expõe um endpoint compatível com MCP em $FOUNDRY_PROJECT_ENDPOINT/toolboxes/file-search-toolbox/versions/<version>/mcp?api-version=v1, onde <version> é a versão retornada pela chamada anterior.

  2. Crie uma conexão de projeto de ferramenta remota que aponte para o ponto de extremidade da caixa de ferramentas, usando um token Entra do usuário para que a identidade do chamador seja passada (audiência https://ai.azure.com).

    azd ai connection create file-search-toolbox-conn \
  --kind remote-tool \
  --target "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/file-search-toolbox/versions/<version>/mcp?api-version=v1" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com

  3. Crie um agente que use a caixa de ferramentas anexando-a como uma ferramenta MCP.

    curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
    "name": "<AGENT_NAME>-file-search",
    "description": "Agent with file search",
    "definition": {
      "kind": "prompt",
      "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
      "tools": [
        {
          "type": "mcp",
          "server_label": "toolbox",
          "server_url": "'$FOUNDRY_PROJECT_ENDPOINT'/toolboxes/file-search-toolbox/versions/<version>/mcp?api-version=v1",
          "require_approval": "never",
          "project_connection_id": "file-search-toolbox-conn"
        }
      ],
      "instructions": "You are a customer support chatbot. Use file search results from the vector store to answer questions based on the uploaded files."
    }
  }'

Seleção dinâmica do armazenamento vetorial (sobrescrita de parâmetro)

Ao adicionar a pesquisa de arquivos a uma caixa de ferramentas, você pode fornecer vector_store_ids de duas maneiras:

  • Fixada na criação da caixa de ferramentas — inclua vector_store_ids na configuração da ferramenta (como mostrado no exemplo anterior). O repositório de vetores é fixo em cada chamada e não pode ser sobrescrito em tempo de execução.
  • Dinâmico em runtime (substituição de parâmetro) — omita vector_store_ids da configuração da ferramenta. Os chamadores o fornecem nos argumentos tools/call, para que cada chamada possa ter como destino um repositório de vetores diferente. Isso permite cenários como repositórios de documentos multilocatários em que cada solicitação pesquisa um conjunto diferente de arquivos.

Crie a caixa de ferramentas sem vector_store_ids:

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/file-search-toolbox/versions?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "File search with dynamic vector store",
    "tools": [
      { "type": "file_search" }
    ]
  }'

Quando você omite vector_store_ids, os chamadores o passam nos argumentos tools/call:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"file_search","arguments":{"queries":["search text"],"vector_store_ids":["<VECTOR_STORE_ID>"]}}}

Nota

A API REST, o SDK do Python, o SDK do .NET, o SDK do JavaScript e a CLI do Desenvolvedor Azure dão suporte dinâmicovector_store_ids. Atualmente, a interface do usuário do portal do Foundry requer vector_store_ids quando você adiciona uma ferramenta de Pesquisa de Arquivos.

Importante

Quando você usa a Pesquisa de Arquivos por meio de uma caixa de ferramentas em um agente hospedado, não há suporte para o isolamento do usuário. Todos os usuários no mesmo projeto compartilham acesso a quaisquer repositórios de vetores referenciados na configuração da ferramenta ou fornecidos em runtime.

curl --request POST \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": {
    "type": "agent_reference",
    "name": "<AGENT_NAME>-file-search"
  },
  "metadata": {
    "test_response": "file_search_enabled",
    "vector_store_id": "'$VECTOR_STORE_ID'"
  },
  "input": [{
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Can you search the uploaded file and tell me about Azure TV instructions?"
      }
    ]
  }],
  "stream": true
}'

A resposta retorna uma saída em streaming que contém a resposta do agente com base nas informações recuperadas do armazenamento vetorial. O agente pesquisa no seu arquivo carregado para responder à consulta sobre as instruções da Azure TV.

Limpar

Exclua o agente.

curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/<AGENT_NAME>-file-search?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN"

Exclua o repositório de vetores.

curl --request DELETE \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/vector_stores/$VECTOR_STORE_ID \
  -H "Authorization: Bearer $AGENT_TOKEN"

Exclua o arquivo.

curl --request DELETE \
  --url $FOUNDRY_PROJECT_ENDPOINT/openai/v1/files/$FILE_ID \
  -H "Authorization: Bearer $AGENT_TOKEN"

Referências

Verificar os resultados da pesquisa de arquivo

Depois de executar um exemplo de código neste artigo, verifique se a pesquisa de arquivos está funcionando:

  • Confirme se o repositório de vetores e o arquivo foram criados.
    • Nos exemplos de Python e TypeScript, os auxiliares de upload e consulta são concluídos somente após a conclusão da ingestão.
  • Faça uma pergunta que você só pode responder do conteúdo carregado.
  • Confirme se a resposta está fundamentada em seus documentos.

Fontes de arquivo

  • Carregar arquivos locais (configuração de agente Básico e Standard)
  • Armazenamento de Blobs do Azure (somente configuração padrão)

Comportamento de pesquisa de arquivo por tipo de instalação do agente

Configuração básica do agente

A ferramenta de pesquisa de arquivos tem a mesma funcionalidade que a API de Respostas do Azure OpenAI. A ferramenta usa Microsoft recursos de pesquisa e armazenamento gerenciados.

  • Você armazena arquivos carregados em armazenamento gerenciado pela Microsoft.
  • Você cria um repositório de vetores usando um recurso de pesquisa gerenciado Microsoft.

Configuração do agente padrão

A ferramenta de pesquisa de arquivos usa os recursos Pesquisa de IA do Azure  e Armazenamento de Blobs do Azure aos quais você se conecta durante a instalação do agente.

  • Você armazena arquivos carregados em sua conta de Armazenamento de Blobs do Azure conectada.
  • Você cria repositórios de vetores usando seu recurso de Pesquisa de IA do Azure  conectado.

Para ambas as configurações do agente, o serviço manipula todo o processo de ingestão, que inclui:

  • Analisar e agrupar documentos automaticamente.
  • Gerando e armazenando inserções.
  • Utilizando pesquisas de vetor e palavra-chave para recuperar conteúdo relevante para consultas de usuário.

O código é idêntico para ambas as configurações. A única variação é onde seus arquivos e repositórios de vetores são armazenados.

Escolha a pesquisa de arquivo quando precisar:

  • Pesquise documentos que você carrega diretamente (PDFs, documentos Word, arquivos de código)
  • Permitir que os agentes respondam a perguntas sobre conteúdos de natureza proprietária ou confidencial
  • Processar arquivos de até 512 MB sem gerenciar a infraestrutura de pesquisa externa

Considere alternativas para estes cenários:

Cenário Ferramenta recomendada
Pesquisar índices de Pesquisa de IA do Azure  existentes Pesquisa de IA do Azure  ferramenta
Pesquisar informações atuais na Web Ferramenta de pesquisa na Web
Combinar várias fontes de dados em uma consulta Usar várias ferramentas em conjunto

Como funciona a pesquisa de arquivos

A ferramenta de pesquisa de arquivos usa as melhores práticas de recuperação para extrair dados relevantes de seus arquivos e melhorar as respostas do modelo.

Processamento de consulta

Quando você envia uma consulta de pesquisa de arquivo:

  1. Reescreve sua consulta para otimize-a para pesquisa.
  2. Divide consultas complexas em pesquisas paralelas.
  3. Executa a pesquisa híbrida combinando a palavra-chave e a correspondência semântica entre repositórios de vetores.
  4. Reclassificado os resultados para selecionar o conteúdo mais relevante para a resposta.

Configurações de agrupamento padrão

Configuração Valor padrão
Tamanho da parte 800 tokens
Sobreposição de fragmentos 400 tokens
Modelo de inserção text-embedding-3-large (256 dimensões)
Máximo de blocos no contexto 20

Repositórios de vetores

Os objetos do repositório de vetores dão à ferramenta de pesquisa de arquivos a capacidade de pesquisar seus arquivos. Quando você adiciona um arquivo a um repositório de vetores, o processo analisa automaticamente, agrupa, inseri e armazena o arquivo em um banco de dados vetor que dá suporte à palavra-chave e à pesquisa semântica. Cada repositório de vetores pode armazenar até 10.000 arquivos. Você pode anexar repositórios de vetores a agentes e conversas. No momento, você pode anexar no máximo um repositório de vetores a um agente e um repositório de vetores a uma conversa.

Para obter conceitos em segundo plano e diretrizes de ciclo de vida (preparação, comportamento de exclusão e políticas de expiração), consulte repositórios de vetores para pesquisa de arquivos.

Remova arquivos de um repositório de vetores:

  • Excluindo o objeto de arquivo do repositório de vetores.
  • Excluindo o objeto de arquivo subjacente. Essa ação remove o arquivo de todas as configurações vector_store e code_interpreter em todos os agentes e conversas da sua organização.

O tamanho máximo do arquivo é de 512 MB. Cada arquivo não deve conter mais de 5.000.000 tokens (computados automaticamente quando você anexa um arquivo).

Garantir a prontidão do armazenamento de vetores antes de executar operações

Verifique se o sistema processa totalmente todos os arquivos em um repositório de vetores antes de criar uma execução. Isso garante que todos os dados em seu repositório de vetores sejam pesquisáveis. Verificar a preparação do repositório de vetores usando os auxiliares de sondagem nos SDKs ou sondando manualmente o objeto do repositório de vetores para garantir que o status seja concluído.

Como alternativa, o objeto de execução inclui um tempo de espera máximo de 60 segundos quando o repositório de vetores da conversa contém arquivos que ainda estão em processamento. Essa espera garante que todos os arquivos carregados pelos usuários em uma conversa sejam totalmente pesquisáveis antes que a execução continue. Essa espera de fallback não se aplica ao repositório de vetores do agente.

Repositórios de vetores de conversa têm políticas de expiração padrão

Os repositórios de vetores criados usando auxiliares de conversa (como tool_resources.file_search.vector_stores em conversas ou message.attachments em Mensagens) têm uma política de expiração padrão de sete dias após a última ativa (definida como a última vez em que o repositório de vetores fazia parte de uma execução).

Quando um repositório de vetores expira, as execuções nessa conversa falham. Para corrigir esse problema, recrie um novo repositório de vetores com os mesmos arquivos e reanexe-o à conversa.

Tipos de arquivo com suporte

Nota

Para tipos MIME de texto, a codificação deve ser UTF-8, UTF-16 ou ASCII.

Formato de arquivo Tipo MIME
.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

Limitações

Tenha esses limites em mente ao planejar a integração de pesquisa de arquivos:

  • A pesquisa de arquivos dá suporte a formatos de arquivo e codificações específicos. Consulte os tipos de arquivo com suporte.
  • Cada repositório de vetores pode armazenar até 10.000 arquivos.
  • Você pode anexar no máximo um repositório de vetores a um agente e um repositório de vetores a uma conversa.
  • Os recursos e a disponibilidade variam de acordo com a região. Consulte o suporte a regiões do Microsoft Foundry.

Solucionando problemas

Questão Causa provável Resolução
401 Não autorizado O token de acesso está ausente, expirado ou com escopo incorreto. Obtenha um token novo e repita a solicitação. Para chamadas REST, confirme se você definiu AGENT_TOKEN corretamente.
403 Proibido A identidade assinada não tem as funções necessárias. Confirme as funções em Pré-requisitos e tente novamente após a conclusão da propagação da atribuição de função.
404 Não Encontrado O ponto de extremidade do projeto ou os identificadores de recurso estão incorretos. Confirme FOUNDRY_PROJECT_ENDPOINT e IDs, como nome do agente, versão, ID do repositório de vetores e ID do arquivo.
As respostas ignoram seus arquivos O agente não está configurado com file_search, ou o repositório de vetores não está anexado. Confirme se a definição do agente inclui file_search e a vector_store_ids lista contém sua ID do repositório de vetores.
O tempo limite para o envio do arquivo expirou Arquivo grande ou conexão de rede lenta. Use upload_and_poll para lidar com arquivos grandes. Considere dividir documentos muito grandes em partes menores.
Falha na criação do armazém vetorial Cota excedida ou formato de arquivo inválido. Verifique os limites do repositório de vetores (10.000 arquivos por repositório). Verifique se há suporte para o formato de arquivo.
A pesquisa retorna resultados irrelevantes Conteúdo do arquivo não indexado corretamente ou consulta muito ampla. Aguarde a conclusão da indexação (verificar vector_store.status). Use consultas mais específicas.
Nenhuma citação em resposta O modelo não usou a pesquisa de arquivo ou o conteúdo não foi encontrado. Use tool_choice="required" para forçar a pesquisa de arquivos. Verifique se o conteúdo do arquivo corresponde ao tópico da consulta.

Conteúdo relacionado

  • Last updated on