Strumenti server

Gli strumenti server sono capacità che Synthorai esegue per te dentro una singola richiesta: il modello chiede qualcosa, noi facciamo il lavoro e il risultato torna nella stessa risposta. Aggiungi una voce a tools — nessun secondo endpoint, nessuna callback da implementare.

Strumenti disponibili

Ogni strumento server è identificato dal prefisso synthorai:, quindi non collide mai con i nomi dei tuoi strumenti:

Il contratto condiviso

Ogni strumento server si comporta allo stesso modo: ciò che impari da uno vale per il successivo:

• Solo opt-in. Nulla viene eseguito se non metti lo strumento in tools. Una richiesta senza è una richiesta ordinaria.
• Un solo round trip. Il loop degli strumenti lo guidiamo noi; ricevi una singola risposta con l'attività dello strumento e la risposta già dentro.
• I tuoi strumenti continuano a funzionare. Strumenti server e i tuoi strumenti function possono essere dichiarati insieme — quando il modello chiama uno dei tuoi, ti restituiamo il controllo con un onesto stop_reason: tool_use. (Un'eccezione: i nomi che iniettiamo sono riservati — vedi sotto.)
• Prezzo per chiamata, visibile in usage. I conteggi finiscono in usage.server_tool_use e l'addebito in usage.cost, così ogni richiesta può essere riconciliata con la fattura.
• max_uses è un tetto reale. Limita quanto può spendere una singola richiesta, e regge attraverso i retry interni.

I token sono l'altra metà del costo

Continuare la conversazione

Riaggiungi il messaggio assistant a messages esattamente come lo hai ricevuto, blocchi degli strumenti inclusi. Continua a dichiarare lo stesso strumento server nelle richieste successive così la cronologia resta nella forma più ricca; se togli lo strumento, i risultati precedenti vengono appiattiti in testo semplice ma il modello continua a vederne il contenuto.

Nomi di strumento riservati

Finché usi un parametro synthorai:, il nome nudo corrispondente è riservato: dichiarare un tuo strumento chiamato web_search accanto a synthorai:web_search (o web_fetch accanto a synthorai:web_fetch) restituisce un 400 che nomina lo strumento. Rinomina il tuo, o togli il parametro synthorai:.

Il motivo è che iniettiamo lo strumento server proprio con quel nome: due strumenti arriverebbero al modello con un solo nome e nessuno saprebbe di chi è la chiamata che torna — gli argomenti del tuo strumento potrebbero finire al nostro provider di ricerca, e la tua chiamata potrebbe perdersi. Rifiutare la richiesta è l'unica risposta onesta. Dichiarare un tuo strumento con uno dei due nomi senza il parametro synthorai: corrispondente non è toccato: non iniettiamo nulla, quindi nulla collide.

I fallimenti non si pagano

La tariffa per chiamata si applica alle chiamate che hanno prodotto un risultato. Una chiamata rifiutata prima di lasciare la nostra rete — URL respinto, dominio bloccato, backend non configurato — non costa nulla. Una chiamata arrivata al provider e lì fallita viene addebitata, perché il provider ha addebitato noi. In entrambi i casi il round conta nel budget max_uses, quindi un modello che ritenta un URL rotto non può ciclare gratis.

Quali endpoint lo supportano

Gli strumenti server girano su /v1/messages, /v1/chat/completions e /v1/responses. Inviare un parametro synthorai: a un endpoint che non li supporta — un endpoint Gemini — restituisce un 400 che te lo dice. Preferiamo rifiutare piuttosto che passare uno strumento sconosciuto a monte: nel migliore dei casi un confuso errore di terze parti, nel peggiore viene ignorato in silenzio, la ricerca non avviene mai e paghi una richiesta normale che ha fatto silenziosamente meno di quanto chiesto.

Disponibilità

Gli strumenti server si abilitano per chiave API. Se uno strumento non è abilitato per la tua chiave ricevi un 400 esplicito che lo nomina, invece di un parametro ignorato in silenzio. Contattaci per attivarlo.