Herramienta de búsqueda de archivos para agentes

Creación de un agente con la herramienta de búsqueda de archivos

En el ejemplo de código siguiente se muestra cómo agregar la herramienta de búsqueda de archivos a un cuadro de herramientas y adjuntar el cuadro de herramientas a un agente. Debe cargar archivos y crear un almacén de vectores antes de ejecutar este código. Seleccione Prompt Agents para usar Azure AI Projects SDK y crear un agente de indicaciones del lado del servidor, o Hosted Agents para usar el Agent Framework FoundryChatClient y crear un agente efímero dentro del proceso.

Agentes rápidos

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)

Salida esperada

La salida siguiente procede del ejemplo de código anterior:

[Response text grounded in your uploaded document content]

Referencias

• Referencia: SDK de Azure para Python ejemplo: búsqueda de archivos
• Referencia: API REST de Microsoft Foundry

Agentes hospedados

En este ejemplo se crea el cuadro de herramientas de búsqueda de archivos con el SDK de proyectos de IA de Azure y, a continuación, se usa FoundryChatClient desde Microsoft Agent Framework y se conecta al punto de conexión mcP del cuadro de herramientas mediante FoundryToolbox. Establezca las FOUNDRY_PROJECT_ENDPOINT variables de entorno y FOUNDRY_MODEL e inicie sesión con 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())

Salida esperada

El agente busca el contenido del archivo indexado desde el almacén de vectores y devuelve una respuesta fundamentada. La salida de la consola muestra el texto de respuesta final que contiene la respuesta derivada del archivo cargado.

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

Para obtener el ejemplo completo, consulte foundry_chat_client_with_file_search.py.

Ejemplo de búsqueda de archivos con el agente

En este ejemplo, creará un archivo local, lo cargará en Azure y lo usará en el VectorStore recién creado para la búsqueda de archivos. Seleccione Prompt Agents para usar el SDK de proyectos de IA de Azure para crear un agente de mensajes del lado servidor o Agentes hospedados para usar el marco del agente de Microsoft para crear un agente efímero en proceso.

Agentes rápidos

El código de este ejemplo es sincrónico y de streaming. Para el uso asincrónico, consulte el código sample en el SDK de Azure para .NET repositorio en 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);

Salida esperada

La salida siguiente procede del ejemplo 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

El código siguiente es un fragmento de integración. Crea el cuadro de herramientas de búsqueda de archivos con el SDK de proyectos de IA de Azure y, a continuación, usa la integración de Microsoft Agent FrameworkAddFoundryToolboxes. Para conocer los paquetes necesarios, las importaciones y la implementación de ayuda mantenida, consulte Conectar un agente hospedado a una caja de herramientas y el ejemplo público de caja de herramientas hospedada. Establezca las AZURE_AI_PROJECT_ENDPOINTvariables de entorno , AZURE_OPENAI_ENDPOINTy AZURE_AI_MODEL_DEPLOYMENT_NAME e inicie sesión con az login.

Fragmento de integración dependiente del asistente:

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

Salida esperada

El agente hospedado utiliza el punto de conexión MCP de la caja de herramientas para buscar en el almacén de vectores configurado en la caja de herramientas de búsqueda de archivos y responde con contenido fundamentado.

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

Para obtener una integración mantenida de .NET Agent Framework, consulte Uso de un cuadro de herramientas con un agente hospedado.

Ejemplo de búsqueda de archivos con el agente en escenarios de streaming

En este ejemplo, creará un archivo local, lo cargará en Azure y lo usará en el VectorStore recién creado para la búsqueda de archivos. El código de este ejemplo es sincrónico y de streaming. Para el uso asincrónico, consulte el código sample en el SDK de Azure para .NET repositorio en 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);
    }
}

Salida esperada

La salida siguiente procede del ejemplo 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'.

Búsqueda de archivos de ejemplo con el agente

En el ejemplo de TypeScript siguiente se muestra cómo agregar la herramienta de búsqueda de archivos a un cuadro de herramientas y adjuntar el cuadro de herramientas a un agente. Debe cargar archivos y crear un almacén de vectores antes de ejecutar este código. Consulte la sección Comportamiento de búsqueda de archivos por tipo de instalación del agente a continuación para obtener más información. Para obtener un ejemplo de JavaScript, consulte el código sample en el repositorio SDK de Azure para JavaScript en 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);
});

Salida esperada

[Response text grounded in your uploaded document content]

Referencias

• Referencia: SDK de Azure para el ejemplo de JavaScript: búsqueda de archivos
• Referencia: API REST de Microsoft Foundry

Uso de la búsqueda de archivos en un agente de Java

Agregue la dependencia a pom.xml:

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

Creación de un agente con búsqueda de archivos

Antes de ejecutar este ejemplo, cree un almacén de archivos y un almacén de vectores mediante los endpoints REST {projectEndpoint}/openai/v1/files y {projectEndpoint}/openai/v1/vector_stores. A continuación, cree una caja de herramientas de búsqueda de archivos fuera de banda utilizando el ejemplo de Python, REST, C# o TypeScript, o bien el portal de Foundry. Cree la conexión del proyecto de herramienta remota para el punto de conexión MCP de la caja de herramientas antes de asociarla al 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());
    }
}

Salida esperada

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

Para obtener más ejemplos, como la carga de archivos y la creación del almacén de vectores, consulte los ejemplos Azure AI Agents Java SDK.

Cargar archivos y agregarlos a un almacén de vectores

Para acceder a los archivos, la herramienta de búsqueda de archivos usa el objeto de almacén vectorial. Cargue los archivos y cree un almacén de vectores. A continuación, revise el estado del almacén hasta que todos los archivos hayan salido del estado in_progress, para confirmar que todo el contenido ha sido completamente procesado. El SDK proporciona asistentes para cargar y sondear.

Establezca la siguiente variable de entorno antes de ejecutar los ejemplos:

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

Carga de un archivo

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"

Creación de un almacén de vectores

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

Agregar búsqueda de archivos a un cuadro de herramientas y crear un agente

La manera recomendada de agregar búsqueda de archivos es a través de un cuadro de herramientas y, a continuación, adjuntar el cuadro de herramientas al agente como una herramienta MCP. Consulte ¿Qué es un cuadro de herramientas?

Carga de archivos para el uso del cuadro de herramientas

Para crear un archivo y un almacén de vectores para su uso con una caja de herramientas, cargue el archivo en el punto de conexión de archivos a nivel de recurso con el encabezado x-aml-project-id. Use el GUID del proyecto desde properties.amlWorkspace.internalId.

1. Cargue el archivo: POST {account_endpoint}/openai/v1/files con purpose=assistants y el encabezado x-aml-project-id: {project-guid}.
2. Cree un almacén de vectores: POST {account_endpoint}/openai/v1/vector_stores con el identificador de archivo devuelto y el mismo x-aml-project-id encabezado.

El identificador del almacén de vectores resultante es el valor que se proporciona como <VECTOR_STORE_ID>.

1. Cree un cuadro de herramientas que contenga la herramienta de búsqueda de archivos:

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

   El cuadro de herramientas expone un punto de conexión compatible con MCP en $FOUNDRY_PROJECT_ENDPOINT/toolboxes/file-search-toolbox/versions/<version>/mcp?api-version=v1, donde <version> es la versión devuelta por la llamada anterior.

2. Crea una conexión de proyecto de herramienta remota que apunte al punto de conexión de la caja de herramientas, utilizando un token de usuario de Entra para que se transmita la identidad del solicitante (audience 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. Cree un agente que use el cuadro de herramientas al adjuntarlo como una herramienta 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."
       }
     }'
   

Selección dinámica de almacén vectorial (sobrescritura de parámetros)

Al agregar búsqueda de archivos a un cuadro de herramientas, puede proporcionar vector_store_ids de dos maneras:

• Fijado al crear la caja de herramientas — incluya vector_store_ids en la configuración de la caja de herramientas (como se muestra en el ejemplo anterior). El almacén de vectores está definido para cada llamada y no se puede sobrescribir en tiempo de ejecución.
• Dinámico en tiempo de ejecución (sobrescritura de parámetros) — omite vector_store_ids en la configuración de la herramienta. Los solicitantes lo proporcionan en los tools/call argumentos, de modo que cada llamada puede dirigirse a un almacén de vectores diferente. Esto permite escenarios como almacenes de documentos multiinquilino en los que cada solicitud busca en un conjunto diferente de archivos.

Cree el cuadro de herramientas sin 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" }
    ]
  }'

Cuando se omite vector_store_ids, los llamantes lo pasan en los tools/call argumentos:

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

Creación de una respuesta con búsqueda de archivos

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

La respuesta devuelve la salida en streaming que contiene la respuesta del agente en función de la información recuperada del almacenamiento de vectores. El agente busca en el archivo cargado para responder a la consulta sobre las instrucciones de Azure TV.

Limpieza

Elimine el agente.

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

Borre el almacén de vectores.

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

Elimine el archivo.

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

Referencias

• Referencia: API REST de Microsoft Foundry