Uso degli strumenti e chiamata di funzioni

Consenti a un modello di chiamare le tue funzioni: il ciclo delle richieste, entrambi i formati e gli errori che costano token.

L'uso degli strumenti consente al modello di chiederti di eseguire una funzione e poi proseguire con il risultato. È il meccanismo alla base di ogni agente di programmazione.

Il ciclo

1. Invii messages insieme a tools che descrivono ciò che è disponibile.
2. Il modello risponde con stop_reason: tool_use e un tool_use blocco che indica il nome dello strumento e i suoi argomenti.
3. Tu lo esegui: il gateway non esegue mai il tuo codice.
4. Invii nuovamente l'intera cronologia insieme a un tool_result blocco.
5. Il modello produce la risposta finale oppure richiede un altro strumento.

Definizione degli strumenti (formato Messages)

Copy{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Current weather for a city. Use when the user asks about weather.",
    "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string", "description": "City name"}},
      "required": ["city"]
    }
  }],
  "messages": [{"role": "user", "content": "Weather in Paris?"}]
}

Restituzione di un risultato

Copy{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC...",
    "content": "18C, light rain"
  }]
}

Formato OpenAI

La /v1/chat/completions l'endpoint accetta il formato OpenAI tools / tool_calls invece, con i risultati restituiti come messaggi con ruolo tool.

Quanto costa l'uso degli strumenti

• Le definizioni vengono inviate nuovamente a ogni turno. Venti schemi di strumenti prolissi possono occupare gran parte dei token di input prima ancora che inizi la conversazione.
• I risultati diventano contesto. Uno strumento che restituisce 200 righe di JSON inserisce tutto nella richiesta successiva e in ogni richiesta seguente.
• Ogni ciclo di richiesta e risposta è una chiamata fatturata. Un'attività che richiede cinque strumenti comporta almeno sei richieste.
• Limita la lunghezza dell'output degli strumenti e riassumilo prima di restituirlo. Ridurre un risultato a ciò che serve effettivamente al modello è la modifica più efficace nella maggior parte dei cicli degli agenti.