Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Definizioni degli strumenti

Quando un LLM riceve una richiesta che non può gestire direttamente, esaminerà gli strumenti disponibili per aiutarlo a completare la richiesta. L'LLM seleziona gli strumenti in base alla sua comprensione semantica dei nomi e delle descrizioni degli strumenti forniti e delle eventuali istruzioni fornite nel prompt. Quindi creerà un input basato sullo schema di input definito e si aspetterà un output basato sullo schema di output. Pertanto, la creazione di definizioni descrittive degli strumenti e schemi di input e output convalidati è fondamentale per aiutare l'LLM a selezionare gli strumenti in modo efficace. Esistono generalmente due approcci per creare questa documentazione: l'approccio alla specificazione degli strumenti e l'approccio docstring.

Approccio alla specifica degli strumenti

L'approccio consigliato consiste nel seguire direttamente le specifiche dell'utensile MCP durante la definizione dell'utensile. L'esempio seguente viene mostrato utilizzando il decoratore di strumenti Strands Agent:

@tool(
  name = "search_website",
  description = "This tool searches the provided website for semantic matches to the query provided",
  inputSchema = {
    "json": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "The url of the website to load and search."
        },
        "query": {
          "type": "string",
          "description": "The content you want to try and match in the website."
      }
    },
    "required": ["url", "query"]
  },
  outputSchema = {
    "json": {
      "type": "object",
      "properties": {
      "results": {
          "type": "array",
          "items": {
            "type": "string" 
          }
        }
      }
    }
  }
)
def search_website:
  …

Utilizza campi standard, come, name descriptioninputSchema, e outputSchema assicura che ogni strumento abbia una documentazione coerente che sia l'LLM che gli umani possano comprendere. Ogni strumento dovrebbe definire questi campi come minimo e, facoltativamente, fornire un titolo e delle annotazioni, che sono suggerimenti opzionali sul comportamento dello strumento. Quando possibile, utilizzate le enumerazioni per i valori dei parametri per facilitare la selezione delle opzioni corrette da parte dell'LLM. Le enumerazioni funzionano meglio per insiemi finiti, come valori di status o priorità, ma non sono adatte per testo in formato libero, valori dinamici, numeri arbitrari o identificatori di risorse. In questi casi, fornisci invece descrizioni ed esempi chiari. Includi anche un valore predefinito, quando possibile, in modo che LLM non debba indovinare quale sia l'opzione corretta. Tieni presente che le definizioni degli strumenti sono incluse nel prompt LLM di ogni chiamata e occupano spazio nella finestra contestuale insieme alle istruzioni di sistema e alla cronologia delle conversazioni.

Approccio Docstring

Un altro approccio, se stai scrivendo i tuoi strumenti in Python, è usare le docstring per fornire la descrizione, l'utilizzo e l'output dello strumento. Di seguito è riportato un esempio di questo approccio:

def search_website(url: str, query: str) -> list:
    
    """
    This tool loads the specified website and then attempts to find content that matches the provided query through semantic search. It provides back a list of strings that are the sentences that match the query. 
    Args:
      url: the website url to load
      query: the content you want to semantically match in the website
    """

Le docstring non applicano uno schema o un formato standardizzato. L'utilizzo di questo approccio potrebbe produrre risultati incoerenti in base al modo in cui gli sviluppatori di strumenti scelgono di documentare ogni strumento. La definizione e l'applicazione di uno standard a livello di organizzazione sono essenziali se si segue questo approccio.

Le migliori pratiche per le definizioni degli strumenti MCP