Abilitare la ricerca degli strumenti in una casella degli strumenti

Quando una cassetta degli attrezzi contiene molti strumenti, il fatto di passare tutte le definizioni degli strumenti al modello a ogni turno crea tre problemi che si aggravano a vicenda: i costi in token aumentano con ogni strumento aggiunto al contesto, la finestra di contesto si riempie di definizioni che l’attività in corso non richiede e il modello sceglie gli strumenti sbagliati da un elenco sovraffollato. La ricerca degli strumenti risolve questo problema sostituendo l'elenco completo degli strumenti con due meta-strumenti incentrati, quindi i costi rimangono flat indipendentemente dalle dimensioni della casella degli strumenti.

Quando si abilita la ricerca degli strumenti, il modello ottiene due meta-strumenti predefiniti: tool_search, che chiama con una descrizione in linguaggio naturale della funzionalità necessaria e call_tool, che usa per richiamare qualsiasi strumento individuato in base al nome. Foundry valuta le query tool_search nell'intero insieme di strumenti del toolbox e restituisce solo quelli corrispondenti, in modo che il contesto attivo rimanga mirato e pertinente.

Per l'individuazione nell'ambito della richiesta delle definizioni degli strumenti differiti, vedere Usare la ricerca degli strumenti con l'API Risposte di Azure OpenAI.

Usa la ricerca degli strumenti quando:

  • Il tuo set di strumenti contiene più di 10–15 strumenti e vuoi evitare il sovraccarico del contesto.
  • Diverse attività dell'agente richiedono subset diversi di strumenti e si vuole che il modello scegli il sottoinsieme corretto in modo dinamico.

Prerequisiti

Funzionamento della ricerca degli strumenti

Quando si include {"type": "toolbox_search"} in una casella degli strumenti, la risposta iniziale tools/list nasconde tutti gli strumenti nella casella degli strumenti. Foundry aggiunge invece due meta-strumenti:

  • tool_search — il modello chiama questo strumento con una descrizione in linguaggio naturale della funzionalità necessaria. Foundry valuta la query e restituisce le definizioni degli strumenti corrispondenti.
  • call_tool — il modello usa questo strumento per richiamare qualsiasi strumento individuato in base al nome.

Il modello non esplora un elenco completo degli strumenti. Descrive la finalità, individua gli strumenti giusti e li chiama.

Meccanismo di ricerca

La ricerca degli strumenti usa BM25 (Best Matching 25), un algoritmo di classificazione probabilistica che assegna punteggi agli strumenti in base al livello di corrispondenza dei metadati della query. BM25 considera la frequenza dei termini, la frequenza dei documenti inversa e la normalizzazione della lunghezza dei documenti per classificare i risultati. Quando il modello chiama tool_search, Foundry indicizza il nome, la descrizione e le informazioni sui parametri di ogni strumento, quindi restituisce le corrispondenze di punteggio superiore per la query.

Parameters

La tool_search funzione accetta i parametri seguenti:

Parametro TIPO Obbligatorio Description
query string Sì Descrizione in linguaggio naturale della funzionalità o dell'attività per cui è necessario uno strumento.
limit integer No Numero massimo di strumenti da restituire. Assume il valore predefinito 5. Il valore massimo è 10.

Il modello può chiamare tool_search il numero di volte necessario durante un singolo turno. Ogni chiamata restituisce solo gli strumenti che corrispondono alla query, quindi il contesto attivo rimane incentrato su ciò che è rilevante per il passaggio corrente. Gli strumenti restituiti da tool_search rimangono chiamabili per il resto del turno senza la ricerca ripetuta.

Note

La voce toolbox_search è una direttiva di configurazione che attiva la ricerca degli strumenti. Non compare in tools/list stesso e non viene conteggiato ai fini del limite di strumenti senza nome per tipo.

Aggiungi {"type": "toolbox_search"} all'elenco degli strumenti della versione della casella degli strumenti. Tutti gli altri strumenti nella casella degli strumenti sono disponibili tramite la ricerca degli strumenti. L'elenco iniziale degli strumenti visualizzato dal modello non li espone.

Usare Foundry Toolkit per Visual Studio Code per abilitare la ricerca degli strumenti quando si crea o si modifica una casella degli strumenti. La casella di controllo Ricerca strumenti aggiunge la voce di configurazione toolbox_search alla versione della toolbox.

  1. Selezionare Foundry Toolkit nella barra delle attività.
  2. In Risorse personali, espandi Il nome del tuo progetto>Strumenti.
  3. Selezionare l'icona + Aggiungi casella degli strumenti .
  4. Nella scheda Compila casella degli strumenti personalizzata immettere il nome e la descrizione della casella degli strumenti e aggiungere gli strumenti desiderati.
  5. Selezionare Ricerca strumenti.
  6. Seleziona Pubblica.

La pubblicazione di una nuova casella degli strumenti crea la prima versione. Tale versione diventa automaticamente la versione predefinita. Per il flusso di lavoro completo per la creazione della casella degli strumenti, vedere Curare la casella degli strumenti basata sulle finalità in Foundry.

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, ToolSearchToolboxTool

project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# ToolSearchToolboxTool() enables tool search — other tools in the toolbox are discovered on
# demand through tool_search instead of being listed up front. Add as many MCP servers as you need;
# tool search keeps the agent's initial tool surface small regardless of toolbox size.
inner_mcp_tool = MCPToolboxTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="never",
    project_connection_id="github-mcp-conn",
)

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Large toolbox with tool search enabled",
    tools=[inner_mcp_tool, ToolSearchToolboxTool()],
)
print(f"Created toolbox `{toolbox_version.name}` (version {toolbox_version.version})")

Per fissare strumenti critici o aggiungere parole chiave di ricerca per strumenti specifici, utilizza tool_configs nella relativa voce dello strumento. Vedere Ottimizzare l'individuazione degli strumenti.

POST {project_endpoint}/toolboxes/my-toolbox/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Large toolbox with tool search enabled",
  "tools": [
    {
      "type": "toolbox_search"
    },
    {
      "type": "work_iq_preview",
      "project_connection_id": "{workiq-connection-id}",
      "tool_configs": {
        "calendar_events": {
          "pin": true,
          "additional_search_text": "meetings appointments schedule calendar invites"
        }
      }
    },
    {
      "type": "mcp",
      "server_label": "github",
      "server_url": "https://api.githubcopilot.com/mcp",
      "require_approval": "never",
      "project_connection_id": "github-mcp-conn"
    }
  ]
}

Note

Usare l'ambito del token https://ai.azure.com/.default quando si recupera il bearer token.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
DefaultAzureCredential credential = new();
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

// ToolSearchToolboxTool enables tool search — other tools are discovered on demand via tool_search
MCPToolboxTool mcpTool = new(serverLabel: "github")
{
  ServerUri = new Uri("https://api.githubcopilot.com/mcp"),
  ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(
    GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
};
ToolSearchToolboxTool searchTool = new()
{
    Name = "ToolBoxSearch",
    Description = "Search for tools by capability"
};

ToolboxVersion toolboxVersion = toolboxClient.CreateVersion(
    name: "my-toolbox",
    tools: [mcpTool, searchTool],
    description: "Large toolbox with tool search enabled");
Console.WriteLine($"Created toolbox `{toolboxVersion.Name}` (version {toolboxVersion.Version})");

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"];
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

// { type: "toolbox_search" } enables tool search — other tools in the toolbox are
// discovered on demand through tool_search instead of being listed up front. Add as many MCP
// servers as you need; tool search keeps the agent's initial tool surface small regardless of size.
const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [
    {
      type: "mcp",
      server_label: "github",
      server_url: "https://api.githubcopilot.com/mcp",
      require_approval: "never",
      project_connection_id: "github-mcp-conn",
    },
    { type: "toolbox_search" },
  ],
  { description: "Large toolbox with tool search enabled" },
);
console.log(`Created toolbox \`${toolboxVersion.name}\` (version ${toolboxVersion.version})`);

Verificare che la ricerca degli strumenti sia attiva

Usare l'endpoint specifico della versione per verificare che tool_search, call_tool e tutti gli strumenti bloccati siano visualizzati in tools/list. Gli strumenti ordinari della casella degli strumenti non aggiunti ai preferiti devono rimanere nascosti nell'elenco iniziale.

Foundry Toolkit crea e pubblica la casella degli strumenti. Per verificare la risposta dell'endpoint MCP per una versione specifica della casella degli strumenti, selezionare la scheda Python, .NET, JavaScript o API REST in questa sezione.

Installare MCP Client SDK se non è già stato fatto:

pip install mcp

import asyncio
from azure.identity import DefaultAzureCredential
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1"
expected_pinned_tools = {"calendar_events"}  # Match the tools configured with pin=True.

token = DefaultAzureCredential().get_token("https://ai.azure.com/.default").token
headers = {
    "Authorization": f"Bearer {token}",
}

async def verify_toolbox():
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List the two meta-tools and any explicitly pinned tools.
            tools_result = await session.list_tools()
            print(f"Tools found: {len(tools_result.tools)}")
            for tool in tools_result.tools:
                print(f"  - {tool.name}: {(tool.description or '')[:80]}")

            names = {tool.name for tool in tools_result.tools}
            meta_tools = {"tool_search", "call_tool"}
            assert meta_tools <= names, "Tool Search meta-tools are missing -- check toolbox_search config"
            assert expected_pinned_tools <= names, "A configured pinned tool is missing"

            unexpected_tools = names - meta_tools - expected_pinned_tools
            assert not unexpected_tools, f"Unpinned tools are visible: {sorted(unexpected_tools)}"

asyncio.run(verify_toolbox())

Usare l'endpoint specifico della versione (/versions/{version}/mcp) per convalidare prima dell'innalzamento di livello.

1. Inizializzare la sessione MCP:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

2. Inviare la notifica inizializzata:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","method":"notifications/initialized"}

3. Elencare gli strumenti disponibili:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

In result.tools, confermare che siano presenti tool_search, call_tool e tutti gli strumenti configurati con pin: true. Tutti i normali strumenti non fissati della casella degli strumenti non devono comparire nell'elenco iniziale.

Usare qualsiasi client .NET compatibile con MCP. Acquisire un token con ambito https://ai.azure.com/.default e chiamare tools/list sull'endpoint MCP specifico della versione. Vedere la scheda API REST per la forma della richiesta.

Installare MCP Client SDK se non è già stato fatto:

npm install @modelcontextprotocol/sdk @azure/identity

import { DefaultAzureCredential } from "@azure/identity";
import { Client } from "@modelcontextprotocol/sdk/client";
import {
  StreamableHTTPClientTransport,
} from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const url =
  "https://<account>.services.ai.azure.com/api/projects/<proj>" +
  "/toolboxes/<name>/versions/<version>/mcp?api-version=v1";
// Match the tools configured with pin: true.
const expectedPinnedTools = new Set(["calendar_events"]);

async function verifyToolbox() {
  const credential = new DefaultAzureCredential();
  const tokenResponse = await credential.getToken(
    "https://ai.azure.com/.default",
  );
  if (!tokenResponse) {
    throw new Error("Failed to acquire an access token.");
  }

  // Build the bearer header from the acquired token. Using tokenResponse.token
  // here reveals no secret in source -- it's a variable reference resolved at
  // runtime, not a hardcoded value.
  const authorizationHeader = "Bearer " + tokenResponse.token;
  const transport = new StreamableHTTPClientTransport(new URL(url), {
    requestInit: {
      headers: { Authorization: authorizationHeader },
    },
  });

  const client = new Client({ name: "tool-search-verifier", version: "1.0.0" });
  await client.connect(transport);

  try {
    // List the two meta-tools and any explicitly pinned tools.
    const toolsResult = await client.listTools();
    console.log(`Tools found: ${toolsResult.tools.length}`);
    for (const tool of toolsResult.tools) {
      console.log(`  - ${tool.name}: ${(tool.description ?? "").slice(0, 80)}`);
    }

    const names = new Set(toolsResult.tools.map((tool) => tool.name));
    const metaTools = ["tool_search", "call_tool"];
    for (const metaTool of metaTools) {
      if (!names.has(metaTool)) {
        throw new Error(
          `Tool Search meta-tool "${metaTool}" is missing -- check toolbox_search config`,
        );
      }
    }
    for (const pinnedTool of expectedPinnedTools) {
      if (!names.has(pinnedTool)) {
        throw new Error(`A configured pinned tool is missing: ${pinnedTool}`);
      }
    }

    const unexpectedTools = [...names].filter(
      (name) => !metaTools.includes(name) && !expectedPinnedTools.has(name),
    );
    if (unexpectedTools.length > 0) {
      throw new Error(`Unpinned tools are visible: ${unexpectedTools.join(", ")}`);
    }
  } finally {
    await client.close();
  }
}

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

Perfezionare la ricerca degli strumenti

La ricerca degli strumenti funziona senza configurazione aggiuntiva. Per schemi di utilizzo prevedibili, regola come strumenti specifici vengono visualizzati e indicizzati.

Foundry Toolkit supporta l'abilitazione della ricerca degli strumenti. Per configurare strumenti aggiunti o parole chiave di ricerca aggiuntive, selezionare la scheda Python, .NET, JavaScript o API REST in questa sezione.

Aggiungi strumenti essenziali ai preferiti

Usare pin per fare in modo che uno strumento specifico venga sempre visualizzato insieme tools/list a tool_search e call_tool. Gli strumenti fissati possono essere richiamati immediatamente senza un passaggio di ricerca aggiuntivo. Per aggiungere ogni strumento in un server MCP o una voce predefinita dello strumento, usare "*" come chiave.

tools=[
    {"type": "toolbox_search"},
    {
        "type": "mcp",
        "server_label": "analytics",
        "server_url": "https://db-mcp.internal/sse",
        "tool_configs": {
            "execute_query": {"pin": True},  # always visible — no search needed
        },
    },
]

{
  "tools": [
    { "type": "toolbox_search" },
    {
      "type": "mcp",
      "server_label": "analytics",
      "server_url": "https://db-mcp.internal/sse",
      "tool_configs": {
        "execute_query": { "pin": true }
      }
    }
  ]
}

Nell'SDK .NET, associare tool_configs alla voce dello strumento MCP durante la creazione della versione della casella degli strumenti. La forma di configurazione è identica al codice JSON visualizzato nella scheda API REST .

In JavaScript includere tool_configs nell'oggetto strumento MCP passato a project.toolboxes.createVersion:

const tools = [
  { type: "toolbox_search" },
  {
    type: "mcp",
    server_label: "analytics",
    server_url: "https://db-mcp.internal/sse",
    tool_configs: {
      execute_query: { pin: true }, // always visible — no search needed
    },
  },
];

Per fissare ogni strumento in una voce, usare "*" come chiave:

{
    "type": "mcp",
    "server_label": "analytics",
    "server_url": "https://db-mcp.internal/sse",
    "tool_configs": {
        "*": {"pin": True},  # every tool in this server is always visible
    },
}

{
  "type": "mcp",
  "server_label": "analytics",
  "server_url": "https://db-mcp.internal/sse",
  "tool_configs": {
    "*": { "pin": true }
  }
}

Usare la stessa chiave con caratteri jolly "*" all'interno di tool_configs nella voce dello strumento MCP .NET per aggiungere ogni strumento da un server MCP. Vedere la scheda API REST per la forma JSON.

Usare la stessa "*" chiave con caratteri jolly all'interno tool_configs dell'oggetto strumento MCP JavaScript per aggiungere ogni strumento da un server MCP:

{
  type: "mcp",
  server_label: "analytics",
  server_url: "https://db-mcp.internal/sse",
  tool_configs: {
    "*": { pin: true }, // every tool in this server is always visible
  },
}

Aggiungere parole chiave di ricerca

Se la descrizione MCP di uno strumento non corrisponde al vocabolario che gli utenti usano naturalmente, aggiungi parole chiave usando additional_search_text. Il testo aggiuntivo viene usato solo per la classificazione di ricerca: non viene mai esposto al modello nello schema dello strumento.

{
    "type": "mcp",
    "server_label": "analytics",
    "server_url": "https://db-mcp.internal/sse",
    "tool_configs": {
        "execute_query": {
            "pin": True,
            "additional_search_text": "SQL database analytics reporting dashboard queries",
        },
        "list_tables": {
            "additional_search_text": "schema columns metadata table structure discover",
        },
    },
}

{
  "type": "mcp",
  "server_label": "analytics",
  "server_url": "https://db-mcp.internal/sse",
  "tool_configs": {
    "execute_query": {
      "pin": true,
      "additional_search_text": "SQL database analytics reporting dashboard queries"
    },
    "list_tables": {
      "additional_search_text": "schema columns metadata table structure discover"
    }
  }
}

Nell'SDK di .NET impostare additional_search_text (e facoltativamente pin) all'interno di tool_configs nella voce dello strumento MCP. La forma corrisponde al codice JSON visualizzato nella scheda API REST .

In JavaScript impostare additional_search_text (e facoltativamente pin) all'interno tool_configs dell'oggetto strumento MCP passato a project.toolboxes.createVersion:

{
  type: "mcp",
  server_label: "analytics",
  server_url: "https://db-mcp.internal/sse",
  tool_configs: {
    execute_query: {
      pin: true,
      additional_search_text: "SQL database analytics reporting dashboard queries",
    },
    list_tables: {
      additional_search_text: "schema columns metadata table structure discover",
    },
  },
}

Fissaggio automatico

Foundry tiene traccia automaticamente degli strumenti che ogni utente chiama più frequentemente e li espone direttamente in tools/list, senza alcuna configurazione necessaria. Dopo un breve periodo iniziale, gli strumenti usati più spesso vengono visualizzati senza dover effettuare una nuova ricerca. L’insieme degli elementi usati più di frequente è specifico per ciascun utente e viene aggiornato man mano che i modelli di utilizzo cambiano; le voci obsolete vengono rimosse automaticamente nel tempo.

Il blocco automatico si combina con la configurazione esplicita pin e additional_search_text. Fissa fin da subito gli strumenti critici che conosci, aggiungi parole chiave per gli strumenti con nomi ambigui e lascia che il fissaggio automatico gestisca la coda lunga con l’emergere dei modelli di utilizzo.

Informazioni di riferimento sulla configurazione

Campo TIPO Obbligatorio Description
type "toolbox_search" Sì Attiva la ricerca dello strumento per la casella degli strumenti.

Includere {"type": "toolbox_search"} nell'elenco degli strumenti della casella degli strumenti per abilitare la ricerca degli strumenti. Tutti gli altri campi di configurazione sono facoltativi.

tool_configs (per ogni strumento)

Impostare tool_configs su una singola voce dello strumento MCP per controllare il comportamento di strumenti specifici all'interno del contesto di ricerca. Usare il nome esatto di uno strumento come chiave per configurare uno strumento specifico oppure "*" per applicare la configurazione a tutti gli strumenti di quella voce.

Campo TIPO Description
pin boolean Quando true, lo strumento viene visualizzato direttamente in tools/list, accanto a tool_search e call_tool. Il modello può invocarlo senza effettuare prima una ricerca.
additional_search_text string Parole chiave aggiuntive aggiunte alla voce dell'indice di ricerca dello strumento. Usato solo per la classificazione della ricerca, mai visibile al modello nello schema dello strumento.

Considerazioni

  • Tutti gli strumenti della casella degli strumenti sono nascosti dall'elenco iniziale. Quando toolbox_search si trova in una casella degli strumenti, non vengono visualizzati altri strumenti della casella degli strumenti in tools/list. Il modello li individua solo tramite tool_search. Gli strumenti aggiunti direttamente a un agente al di fuori della toolbox non subiscono modifiche e rimangono visibili.
  • Le descrizioni degli strumenti determinano la qualità delle corrispondenze. Foundry usa nomi e descrizioni degli strumenti per valutare le query di ricerca. È improbabile che uno strumento privo di descrizione, o con una descrizione vaga, venga restituito anche per query pertinenti. Scrivere descrizioni che descrivono le operazioni dello strumento e i tipi di attività gestiti.
  • tool_search non viene conteggiato ai fini dei limiti degli strumenti. La piattaforma lo inserisce e non occupa lo slot unnamed-tool-per-type.
  • Sono supportate più ricerche a turno. Il modello può chiamare tool_search più volte in un unico turno se diversi passaggi richiedono funzionalità diverse.
  • Gli strumenti restituiti rimangono per il turno. Una volta restituito uno strumento da tool_search, il modello può chiamarlo più volte senza eseguire nuovamente la ricerca.
  • Gli strumenti bloccati vengono sempre visualizzati in tools/list. Gli strumenti con "pin": True in tool_configs appaiono insieme a tool_search e call_tool a ogni turno, indipendentemente dalle query di ricerca.
  • Il fissaggio automatico fa trasparire automaticamente gli strumenti usati di frequente. Foundry tiene traccia della frequenza di chiamata degli strumenti per ciascun utente e promuove gli strumenti chiamati più spesso a tools/list dopo un breve periodo iniziale. L'insieme dei dati usati più frequentemente è specifico per ogni utente e viene aggiornato con l'evolversi dei modelli di utilizzo.
  • Potrebbe essere necessario il consenso OAuth. Se uno strumento nella casella degli strumenti si connette a un server MCP basato su OAuth, la prima chiamata restituisce un CONSENT_REQUIRED errore (codice -32006) con un URL di consenso nella risposta. Aprire l'URL in un browser, completare il flusso OAuth, quindi riprovare. Le chiamate successive hanno esito positivo senza richiedere nuovamente la conferma. Vedere Risolvere gli errori della casella degli strumenti per la gestione di questo errore.

Procedure consigliate

  • Aggiungere una descrizione a ogni strumento. La ricerca degli strumenti usa le descrizioni per associare gli strumenti alle query. Una descrizione mancante o vaga causa una scarsa individuazione.
  • Usare la funzione di ricerca degli strumenti per set di strumenti di grandi dimensioni. Questa configurazione è più efficace quando si dispone di 10 o più strumenti.
  • Usare la ricerca degli strumenti insieme al controllo delle versioni della casella degli strumenti. Verifica la configurazione su un endpoint specifico per una versione prima di promuoverla come impostazione predefinita.
  • Menziona la ricerca degli strumenti nel prompt di sistema. Guidare il modello a chiamare tool_search prima di concludere che una funzionalità non è disponibile. Ad esempio: "Se è necessario uno strumento che non si trova nell'elenco corrente, chiamare tool_search con una descrizione di ciò di cui hai bisogno prima di rispondere che non puoi aiutarti".
  • Fissare gli strumenti sempre necessari. Utilizzare "pin": True in tool_configs per gli strumenti richiamati quasi a ogni turno, così da evitare il passaggio di andata e ritorno della ricerca.
  • Usare additional_search_text quando le descrizioni sono ambigue. Se il team usa un vocabolario diverso rispetto alle descrizioni degli strumenti del server MCP, aggiungere parole chiave per migliorare la precisione della ricerca senza modificare il server.

Risoluzione dei Problemi

Sintomo Causa possibile Correzione
tool_search manca in tools/list toolbox_search non era incluso nella versione del toolbox oppure sei connesso a una versione precedente a questa modifica. Aggiungere {"type": "toolbox_search"} all'elenco degli strumenti e creare una nuova versione. Verificare di usare l'endpoint della versione aggiornata.
tool_search non restituisce alcun risultato per una query Gli strumenti nella cassetta degli strumenti non hanno descrizioni oppure le descrizioni non sono pertinenti alla query. Aggiungere o migliorare le descrizioni degli strumenti nella casella degli strumenti. Le descrizioni devono spiegare le operazioni dello strumento e i tipi di attività gestiti.
Uno strumento della casella degli strumenti viene visualizzato inizialmente in tools/list Lo strumento è stato aggiunto direttamente all'agente anziché, o in aggiunta, alla definizione della toolbox. Rimuovere lo strumento dall'elenco degli strumenti diretti dell'agente e fare affidamento sulla casella degli strumenti. Gli strumenti aggiunti direttamente a un agente sono sempre visibili, indipendentemente dalla ricerca degli strumenti.
Il modello non chiama mai tool_search Il modello non sa che tool_search può recuperare strumenti aggiuntivi. Aggiungere un'istruzione nel prompt del sistema che indica al modello di chiamare tool_search quando una funzionalità necessaria non è presente nell'elenco degli strumenti corrente.
tool_search viene chiamato ma lo strumento restituito non riesce a eseguire La connessione o la configurazione dello strumento sottostante non è valida. Verificare il project_connection_id e gli altri campi sullo strumento restituito. Testa lo strumento direttamente tramite l'endpoint MCP del toolbox senza abilitare la ricerca degli strumenti.

Contenuti correlati

  • Last updated on