Ferramentas de servidor

Ferramentas de servidor são capacidades que a Synthorai executa por você dentro de uma única requisição: o modelo pede algo, fazemos o trabalho e o resultado volta na mesma resposta. Você adiciona uma entrada em tools — não há segundo endpoint nem callback a implementar.

Ferramentas disponíveis

Toda ferramenta de servidor é identificada pelo prefixo synthorai:, então nunca colide com os nomes das suas próprias ferramentas:

Parâmetro	Descrição	Preço
`synthorai:web_search`	Pesquisar na web e ler os resultados.	$0.01
`synthorai:web_fetch`	Ler o texto completo de uma página cuja URL você já tem.	$0.01

O contrato compartilhado

Toda ferramenta de servidor se comporta da mesma forma, então o que você aprende com uma vale para a próxima:

Somente opt-in. Nada executa a menos que você coloque a ferramenta em tools. Uma requisição sem ela é uma requisição comum.
Uma única ida e volta. Nós conduzimos o loop de ferramentas por você; você recebe uma única resposta já com a atividade da ferramenta e a resposta.
Suas próprias ferramentas continuam funcionando. Ferramentas de servidor e suas ferramentas function podem ser declaradas juntas — quando o modelo chama uma das suas, devolvemos o controle com um honesto stop_reason: tool_use. (Uma exceção: os nomes que injetamos são reservados — veja abaixo.)
Preço por chamada, visível em usage. As contagens ficam em usage.server_tool_use e a cobrança em usage.cost, então toda requisição pode ser conciliada com a fatura.
max_uses é um teto real. Limita o que uma única requisição pode gastar, e vale através das novas tentativas internas.

Tokens são a outra metade do custo

A taxa por chamada é só parte do custo de uma requisição. O que a ferramenta traz — trechos de busca, corpo de página — entra na conversa como tokens de entrada, cobrados à tarifa normal do modelo. Em páginas longas esse custo em tokens costuma ser o número maior. E como o gateway roda o loop internamente, usage.input_tokens é a soma de todos os turnos internos, visivelmente maior que o prompt enviado. É o custo real de devolver resultados ao modelo, não cobrança dupla.

Continuando a conversa

Anexe a mensagem do assistant de volta em messages exatamente como recebeu, incluindo os blocos de ferramenta. Continue declarando a mesma ferramenta de servidor nas requisições seguintes para o histórico manter sua forma mais rica; se retirar a ferramenta, os resultados anteriores são achatados em texto puro e o modelo continua vendo o conteúdo.

Nomes de ferramenta reservados

Enquanto você usa um parâmetro synthorai:, o nome puro correspondente fica reservado: declarar sua própria ferramenta chamada web_search ao lado de synthorai:web_search (ou web_fetch ao lado de synthorai:web_fetch) retorna um 400 nomeando a ferramenta. Renomeie a sua, ou remova o parâmetro synthorai:.

O motivo é que injetamos a ferramenta de servidor exatamente com esse nome: duas ferramentas chegariam ao modelo com um só nome e ninguém saberia de quem é a chamada que volta — os argumentos da sua ferramenta poderiam ir ao nosso provedor de busca, e a sua chamada poderia se perder. Recusar a requisição é a única resposta honesta. Declarar uma ferramenta própria com qualquer dos nomes sem o parâmetro synthorai: correspondente não é afetado: não injetamos nada, então nada colide.

Falhas não são cobradas

A taxa por chamada é cobrada de chamadas que produziram resultado. Uma chamada que recusamos antes de sair da nossa rede — URL rejeitada, domínio bloqueado, backend não configurado — não custa nada. Uma chamada que chegou ao provedor e falhou lá é cobrada, porque o provedor nos cobrou. De qualquer forma a rodada conta no orçamento de max_uses, então um modelo repetindo uma URL quebrada não consegue iterar de graça.

Quais endpoints suportam

As ferramentas de servidor rodam em /v1/messages, /v1/chat/completions e /v1/responses. Enviar um parâmetro synthorai: a um endpoint que não as suporta — um endpoint Gemini — retorna um 400 avisando. Preferimos recusar a repassar uma ferramenta desconhecida rio acima, onde o melhor caso é um erro confuso de terceiros e o pior é ser ignorada em silêncio: a busca nunca acontece e você paga por uma requisição normal que quietamente fez menos do que pediu.

Disponibilidade

As ferramentas de servidor são habilitadas por chave de API. Se uma ferramenta não estiver habilitada para a sua chave, você recebe um 400 explícito nomeando-a, em vez de um parâmetro ignorado em silêncio. Fale conosco para ativá-la.