Ferramenta de pesquisa de ficheiros para agentes

Use a ferramenta de pesquisa de ficheiros para fundamentar os agentes da Microsoft Foundry nos seus próprios dados. Com a pesquisa de ficheiros, os agentes podem recuperar informações relevantes dos seus documentos e usá-las para gerar respostas mais precisas e conscientes do contexto, complementando os agentes com conhecimentos como informações proprietárias de produtos ou documentos fornecidos pelos utilizadores.

Neste artigo, aprende como:

  • Carregar ficheiros e criar um armazenamento vetorial
  • Configure um agente com a pesquisa de ficheiros ativada
  • Consulte os seus documentos através do agente

Ao usar a configuração padrão do agente, a ferramenta de pesquisa de ficheiros garante que os seus ficheiros permanecem no seu próprio armazenamento. O seu recurso Pesquisa de IA do Azure ingere os ficheiros, por isso mantém controlo total sobre os seus dados.

Importante

A pesquisa de ficheiros tem encargos adicionais para além das taxas baseadas em tokens pelo uso do modelo.

Pré-requisitos

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

  • O pacote SDK para a sua língua:

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

  • Função de Contribuidor de Dados de Blob de Armazenamento na conta de armazenamento do seu projeto (necessária para carregar ficheiros para o armazenamento do seu projeto)

  • Papel de utilizador do Foundry no projeto Foundry para criar e gerir agentes.

    Importante

    As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

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

  • O URL do endpoint do projeto Foundry e o nome da implementação do modelo.

Carregar e consultar um ficheiro

Para o caminho mais curto para uma resposta fundamentada, complete estas ações por ordem:

  1. Cria ou seleciona um ficheiro que contenha um facto que possas testar.
  2. Carregue o ficheiro e adicione-o a um armazenamento vetorial.
  3. Espera que a ingestão termine.
  4. Anexe a pesquisa de ficheiros a um agente e faça uma pergunta que só o ficheiro possa responder.
  5. Verifique se a resposta utiliza o conteúdo carregado e depois apague os recursos que criou.

Os exemplos de Python e TypeScript mostram o fluxo de upload e consulta num único programa. Os requisitos de limpeza variam consoante o exemplo, por isso siga as instruções de limpeza na secção de língua selecionada.

Suporte de utilização

A tabela seguinte mostra o suporte para SDK e configuração.

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

Exemplos de código

Os exemplos seguintes mostram como carregar um ficheiro, criar uma loja vetorial, configurar um agente com a pesquisa de ficheiros ativada e consultar o agente.

Prepare a sua amostra

  • C# hospedado: Instale Microsoft.Agents.AI.Foundry.Hosting e use AddFoundryToolboxes. Consulte o exemplo de kit de ferramentas alojado e mantido.
  • REST: Utilize uma shell compatível com Bash com a CLI do Azure, a Azure Developer CLI e curl. Defina FOUNDRY_PROJECT_ENDPOINT e FOUNDRY_MODEL_DEPLOYMENT_NAME, obtenha um AGENT_TOKEN, e capture os IDs de ficheiro retornado, armazenamento vetorial e versão da toolbox. Os pedidos da caixa de ferramentas permanecem autenticados com o token 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 linguagem, REST ou o portal Foundry para carregar o ficheiro, criar a loja vetorial e a caixa de ferramentas, e criar a ligação remota ao projeto da ferramenta. Para exemplos de clientes Java mantidos, veja os exemplos do Azure AI Agents Java SDK.

Dica

Pode personalizar o comportamento da pesquisa de ficheiros em tempo de execução, como especificar que armazenamento vetorial usar por pedido, usando entradas estruturadas.

Crie um agente com a ferramenta de pesquisa de ficheiros

O exemplo de código seguinte mostra como adicionar a ferramenta de pesquisa de ficheiros a uma caixa de ferramentas e anexá-la a um agente. Precisas de carregar ficheiros e criar um store vetorial antes de executar este código. Selecione Prompt Agents para usar o SDK Azure AI Projects para criar um agente de prompt do lado do servidor, ou Hosted Agents para usar o Agent Framework FoundryChatClient para construir um agente efémero em processo.

Agentes de comando

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)

Produção esperada

A seguinte saída provém do exemplo de código anterior:

[Response text grounded in your uploaded document content]

Referências

Agentes alojados

Este exemplo cria a caixa de ferramentas de pesquisa de ficheiros com o Azure AI Projects SDK e, em seguida, utiliza FoundryChatClient da Microsoft Agent Framework e liga-se ao ponto final MCP da caixa de ferramentas utilizando FoundryToolbox. Defina as variáveis de ambiente FOUNDRY_PROJECT_ENDPOINT e FOUNDRY_MODEL e inicie sessão utilizando 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())

Produção esperada

O agente procura no conteúdo indexado do ficheiro no armazenamento vetorial e devolve uma resposta fundamentada. A saída da consola mostra o texto final da resposta contendo a resposta derivada do ficheiro carregado.

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

Para a amostra completa, veja foundry_chat_client_with_file_search.py.

Exemplo de pesquisa de ficheiro com agente

Neste exemplo, cria um ficheiro local, carrega-o para Azure e usa-o no recém-criado VectorStore para pesquisa de ficheiros. Selecione Prompt Agents para usar o SDK Azure AI Projects para criar um agente de prompt do lado do servidor, ou Hosted Agents para usar o Microsoft Agent Framework para construir um agente efémero em processo.

Agentes de comando

O código neste exemplo é síncrono e em streaming. Para uso assíncrono, veja o código exemplo na SDK do Azure para .NET repositório no 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);

Produção esperada

A seguinte saída provém 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 alojados

O código seguinte é um fragmento de integração. Cria a caixa de ferramentas de pesquisa de ficheiros com o SDK Azure AI Projects, e depois utiliza a integração com o Microsoft Agent FrameworkAddFoundryToolboxes. Para os pacotes necessários, importações e implementação de ajudantes mantidos, veja Ligar um agente alojado a uma caixa de ferramentas e o exemplo de caixa de ferramentas hospedado publicamente. Defina as AZURE_AI_PROJECT_ENDPOINTvariáveis , AZURE_OPENAI_ENDPOINT, e AZURE_AI_MODEL_DEPLOYMENT_NAME de ambiente, e faça login com az login.

Fragmento de integração dependente do assistente:

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();

Produção esperada

O agente alojado utiliza o ponto final MCP da toolbox para pesquisar no armazenamento vetorial configurado na toolbox de pesquisa de ficheiros 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 uma integração mantida com o .NET Agent Framework, veja Usar uma caixa de ferramentas com um agente alojado.

Exemplo de pesquisa de ficheiro com agente em cenários de streaming

Neste exemplo, cria um ficheiro local, carrega-o para Azure e usa-o no recém-criado VectorStore para pesquisa de ficheiros. O código neste exemplo é síncrono e em streaming. Para uso assíncrono, veja o código exemplo na SDK do Azure para .NET repositório no 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);
    }
}

Produção esperada

A seguinte saída provém 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 ficheiros de exemplo com agente

O exemplo seguinte de TypeScript mostra como adicionar a ferramenta de pesquisa de ficheiros a uma caixa de ferramentas e anexá-la a um agente. Precisas de carregar ficheiros e criar um store vetorial antes de executar este código. Consulte a secção de comportamento de pesquisa de ficheiros por tipo de configuração do agente abaixo para mais detalhes. Para um exemplo de JavaScript, veja o código exemplo no repositório SDK do Azure para JavaScript sobre 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);
});

Produção esperada

[Response text grounded in your uploaded document content]

Referências

Use a pesquisa de ficheiros num agente Java

Dica

A maioria dos agentes usa uma caixa de ferramentas para adicionar a ferramenta de pesquisa de ficheiros e anexá-la ao seu agente como uma ferramenta MCP. Se usar o SDK Java, ainda não existe uma API para criar toolboxs. Crie uma caixa de ferramentas usando o Python, REST API, C#, TypeScript ou o portal Foundry, e depois consulte o seu endpoint MCP a partir do 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 ficheiro e uma loja vetorial usando os endpoints REST {projectEndpoint}/openai/v1/files e {projectEndpoint}/openai/v1/vector_stores. Em seguida, crie externamente um conjunto de ferramentas de pesquisa de ficheiros utilizando o exemplo em Python, REST, C# ou TypeScript, ou o portal Foundry. Crie a ligação do projeto remote-tool para o endpoint MCP da toolbox antes de a associar 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());
    }
}

Produção esperada

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

Para mais exemplos incluindo upload de ficheiros e criação de armazenamento vetorial, consulte os Azure AI Agents Java SDK samples.

Carregar ficheiros e adicioná-los a uma loja de vetores

Para aceder aos seus ficheiros, a ferramenta de pesquisa de ficheiros usa o objeto vector store. Carrega os teus ficheiros e cria uma loja vetorial. Depois, verifica o estado da loja até que todos os ficheiros estejam fora do estado de in_progress para garantir que todo o conteúdo tenha sido completamente processado. O SDK fornece ajudantes para carregamento e sondagens.

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 ficheiro

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 armazenamento vetorial

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 ficheiros a uma caixa de ferramentas e criar um agente

A forma recomendada de adicionar pesquisa de ficheiros é através de uma caixa de ferramentas e depois anexar a caixa de ferramentas ao seu agente como uma ferramenta MCP. Veja O que é uma caixa de ferramentas?

Carregar ficheiros para uso na caixa de ferramentas

Para criar um ficheiro e um armazenamento de vetores para utilização com uma toolbox, carregue o ficheiro no endpoint Files de nível de recurso com o cabeçalho x-aml-project-id. Utilize o GUID do projeto de properties.amlWorkspace.internalId.

  1. Carregue o seu ficheiro: POST {account_endpoint}/openai/v1/files com purpose=assistants e o cabeçalho x-aml-project-id: {project-guid}.
  2. Crie um armazenamento vetorial: POST {account_endpoint}/openai/v1/vector_stores com o ID do ficheiro devolvido e o mesmo x-aml-project-id cabeçalho.

O ID de armazenamento vetorial resultante é o valor que fornece como <VECTOR_STORE_ID>.

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

    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
      }
    ]
  }'

    A caixa 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 devolvida pela chamada anterior.

  2. Crie uma ligação de projeto da ferramenta remota que aponte para o endpoint da caixa de ferramentas, usando um token de utilizador do Entra para que a identidade do chamador seja transmitida (destinatário 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. Cria 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 de armazenamento vetorial (substituição de parâmetros)

Quando adiciona pesquisa de ficheiros a uma caixa de ferramentas, pode fornecer vector_store_ids de duas formas:

  • Afixado ao criar a caixa de ferramentas — incluir vector_store_ids na configuração da ferramenta (como mostrado no exemplo anterior). O armazenamento vetorial é fixo para cada chamada e não pode ser sobreposto em tempo de execução.
  • Dinâmica em tempo de execução (substituição de parâmetros) — omitir vector_store_ids da configuração da ferramenta. Quem faz as chamadas fornece esse valor nos tools/call argumentos, para que cada chamada possa ter como destino um armazenamento vetorial diferente. Isto permite cenários como armazenamentos de documentos multitenant onde cada pedido pesquisa um conjunto diferente de ficheiros.

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 omite vector_store_ids, o código chamador passa-o 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, Python SDK, .NET SDK, JavaScript SDK e Azure Developer CLI suportam dinâmica vector_store_ids. A interface do portal Foundry exige vector_store_ids atualmente quando adicionas uma ferramenta de Pesquisa de Ficheiros.

Importante

Quando usas a Pesquisa de Ficheiros através de uma caixa de ferramentas num agente alojado, o isolamento do utilizador não é suportado. Todos os utilizadores do mesmo projeto partilham acesso a quaisquer armazenamentos vetoriais referenciados na configuração da ferramenta ou fornecidos em tempo de execução.

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 devolve um output em fluxo contínuo contendo a resposta do agente com base na informação recuperada do repositório vetorial. O agente pesquisa no ficheiro carregado para responder à dúvida sobre as instruções do Azure TV.

Limpar

Apaga o agente.

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

Apaga o armazém de vetores.

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

Apaga o ficheiro.

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

Referências

Verificar resultados da pesquisa de ficheiros

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

  • Confirme que o armazenamento vetorial e o ficheiro foram criados.
    • Nos exemplos de Python e TypeScript, as funções auxiliares de upload e sondagem só são concluídas depois de a ingestão ser finalizada.
  • Faça uma pergunta que só possa responder a partir do conteúdo que carregou.
  • Confirme que a resposta está fundamentada nos seus documentos.

Fontes do ficheiro

  • Carregar ficheiros locais (configuração de agentes Basic e Standard)
  • Armazenamento de Blobs do Azure (apenas configuração padrão)

Comportamento da pesquisa de ficheiros por tipo de configuração do agente

Configuração básica do agente

A ferramenta de pesquisa de ficheiros tem a mesma funcionalidade da API OpenAI Answers do Azure. A ferramenta utiliza recursos de pesquisa e armazenamento geridos pela Microsoft.

  • Guardas os ficheiros carregados no armazenamento gerido da Microsoft.
  • Cria-se uma loja vetorial usando um recurso de pesquisa gerido pela Microsoft.

Configuração padrão do agente

A ferramenta de pesquisa de ficheiros utiliza os recursos Pesquisa de IA do Azure e Armazenamento de Blobs do Azure a que se liga durante a configuração do agente.

  • Armazena os ficheiros carregados na sua conta Armazenamento de Blobs do Azure conectada.
  • Cria lojas vetoriais usando o seu recurso Pesquisa de IA do Azure ligado.

Para ambas as configurações de agentes, o serviço gere todo o processo de ingestão, que inclui:

  • Análise e fragmentação automática de documentos.
  • Gerar e armazenar embeddings.
  • Utilizando pesquisas vetoriais e por palavras-chave para recuperar conteúdos relevantes para consultas dos utilizadores.

O código é idêntico para ambas as configurações. A única variação é onde os teus ficheiros e armazenamentos vetoriais estão armazenados.

Escolha pesquisa de ficheiros quando precisar:

  • Pesquise entre documentos que carrega diretamente (PDFs, documentos Word, ficheiros de código)
  • Permitir que os agentes respondam a perguntas de conteúdos proprietários ou confidenciais
  • Processar ficheiros até 512 MB sem gerir infraestrutura de pesquisa externa

Considere alternativas para estes cenários:

Cenário Ferramenta recomendada
Procure índices existentes do Pesquisa de IA do Azure Pesquisa de IA do Azure ferramenta
Pesquise na web pública informações atuais Ferramenta de pesquisa web
Combinar múltiplas fontes de dados numa única consulta Use várias ferramentas em conjunto

Como funciona a pesquisa de ficheiros

A ferramenta de pesquisa de ficheiros utiliza as melhores práticas de recuperação para extrair dados relevantes dos seus ficheiros e melhorar as respostas dos modelos.

Processamento de consultas

Quando enviar uma consulta, pesquisa de ficheiros:

  1. Reescreve a tua consulta para a otimizar para a pesquisa.
  2. Decompõe consultas complexas em pesquisas paralelas.
  3. Executa uma pesquisa híbrida que combina correspondência de palavras-chave e semântica entre armazenamentos vetoriais.
  4. Reclassifica os resultados para selecionar o conteúdo mais relevante para a resposta.

Definições padrão de chunking

Configuração Valor padrão
Tamanho do pedaço 800 fichas
Sobreposição de blocos 400 fichas
Modelo de incorporação Incorporação de texto-3-grande (256 dimensões)
Blocos máximos no contexto 20

Armazenamentos vetoriais

Os objetos de armazenamento vetorial dão à ferramenta de pesquisa de ficheiros a capacidade de pesquisar os teus ficheiros. Quando adiciona um ficheiro a um armazenamento vetorial, o processo analisa, fragmenta, incorpora e armazena automaticamente o ficheiro numa base de dados vetorial que suporta tanto pesquisa por palavras-chave como pesquisa semântica. Cada armazenamento vetorial pode armazenar até 10.000 ficheiros. Pode anexar armazenamentos vetoriais tanto a agentes como a conversas. Atualmente, pode-se anexar no máximo um armazenamento vetorial a um agente e, no máximo, um armazenamento vectorial a uma conversa.

Para conceitos de fundo e orientações do ciclo de vida (prontidão, comportamento de eliminação e políticas de expiração), veja Vector stores para pesquisa de ficheiros.

Remover ficheiros de um armazenamento vetorial através de:

  • A apagar o ficheiro de objeto de armazenamento vetorial.
  • Eliminar o objeto de ficheiro subjacente. Esta ação remove o ficheiro de todas vector_store as code_interpreter configurações e de todos os agentes e conversas da sua organização.

O tamanho máximo do ficheiro é de 512 MB. Cada ficheiro não deve conter mais do que 5.000.000 de tokens (calculados automaticamente quando se anexa um ficheiro).

Garantir a prontidão do armazenamento vetorial antes de iniciar processos

Garanta que o sistema processa completamente todos os ficheiros num armazenamento vetorial antes de criar uma execução. Isto garante que todos os dados na sua loja vetorial são pesquisáveis. Verifique a prontidão do armazenamento vetorial usando os auxiliares de sondagem nos SDKs, ou consultando manualmente o objeto de armazenamento vetorial para garantir que o estado está concluído.

Como alternativa, o objeto run inclui uma espera máxima de 60 segundos quando o armazenamento vetorial da conversa contém ficheiros que ainda estão a ser processados. Esta espera garante que quaisquer ficheiros que os seus utilizadores carreguem numa conversa sejam totalmente pesquisáveis antes da execução continuar. Este tempo de espera de contingência não se aplica à memória vetorial do agente.

As lojas de vetores de conversação possuem políticas de expiração padrão

As lojas vetoriais que crias usando ajudantes 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 atividade (definida como a última vez que a loja vetorial fez parte de uma execução).

Quando um armazenamento vetorial expira, as execuções dessa conversa falham. Para resolver este problema, recrie um novo armazenamento vetorial com os mesmos ficheiros e volte a anexá-lo à conversa.

Tipos de ficheiros suportados

Nota

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

Formato de ficheiro 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 estes limites em mente ao planear a integração da pesquisa de ficheiros:

  • A pesquisa de ficheiros suporta formatos e codificações específicas. Ver Tipos de ficheiro suportados.
  • Cada armazenamento vetorial pode armazenar até 10.000 ficheiros.
  • Pode associar, no máximo, um armazenamento vetorial a um agente e um armazenamento vetorial a uma conversa.
  • As funcionalidades e a disponibilidade variam consoante a região. Consulte o suporte regional do Microsoft Foundry.

Resolução de problemas

Problema Causa provável Resolução
401 Não Autorizado O token de acesso está em falta, expirado ou com a abrangência incorreta. Arranja um token novo e tenta novamente o pedido. Para chamadas REST, confirma que configuraste AGENT_TOKEN corretamente.
403 Proibido A identidade registada não tem as funções exigidas. Confirme os papéis em Pré-requisitos e tente novamente depois de a atribuição de funções terminar de se propagar.
404 Não Encontrado O endpoint do projeto ou os identificadores de recursos estão incorretos. Confirme FOUNDRY_PROJECT_ENDPOINT e IDs, tais como nome do agente, versão, ID da loja vetorial e ID do ficheiro.
As respostas ignoram os seus ficheiros O agente não está configurado com file_search, ou o armazenamento vetorial não está anexado. Confirme que a definição do agente inclui file_search e que a lista vector_store_ids contém o ID do seu armazenamento vetorial.
O carregamento do ficheiro excedeu o tempo limite Ficheiros grandes ou ligação de rede lenta. Uso upload_and_poll para gerir ficheiros grandes. Considere fragmentar documentos muito grandes.
Falha na criação de armazenamento vetorial Quota excedida ou formato de ficheiro inválido. Verifique os limites de armazenamento vetorial (10.000 ficheiros por loja). Verificar que o formato de ficheiro é suportado.
A pesquisa devolve resultados irrelevantes O conteúdo do ficheiro não está devidamente indexado ou a consulta é demasiado ampla. Aguarde que a indexação termine (verificado vector_store.status). Use consultas mais específicas.
Sem citações em resposta O modelo não usou a pesquisa de ficheiros nem encontrou o conteúdo. Use tool_choice="required" para forçar a pesquisa de ficheiros. Verifica se o conteúdo do ficheiro corresponde ao tema da tua consulta.

Conteúdo relacionado

  • Last updated on