Ferramentas integradas na API do Sabiá
As ferramentas que o Sabiá já usa no chat (busca na web, execução de código e Data Ocean) agora estão disponíveis na API. Você ativa as que precisar em cada requisição.
No chat do Sabiá, o modelo já pesquisa na web, executa código e consulta dados oficiais do Brasil enquanto responde. Agora essas mesmas ferramentas estão disponíveis na API: você as ativa na própria requisição e elas rodam dentro da infraestrutura da Maritaca, sem que você precise construir nem manter nenhuma delas.
A diferença em relação à chamada de funções é importante. Na chamada de funções, o modelo devolve o trabalho para o seu código executar. Nas ferramentas integradas, o trabalho acontece dentro da Maritaca: o modelo decide quais ferramentas usar, as chama em vários passos e retorna apenas a resposta final. No chat isso já acontecia nos bastidores. Na API, você escolhe quais ferramentas ligar e recebe o resultado pronto para usar na sua aplicação.
As três ferramentas
São três ferramentas, ativadas de forma independente. Cada uma cobre um tipo de necessidade.
| Ferramenta | Flag na API | Modelos | O que faz |
|---|---|---|---|
| Busca na web | web_search | Todos os modelos Sabiá | Pesquisa na web e lê o conteúdo das páginas para responder com informação atualizada e a devida fonte. |
| Execução de código | code_execution | Apenas sabia-4-thinking | Roda Python e Bash em um sandbox para calcular, analisar dados e gerar arquivos, como gráficos e documentos. |
| Data Ocean | data_ocean | Apenas sabia-4-thinking | Consulta dezenas de bases oficiais brasileiras, de população e empresas a saúde, clima, segurança e economia, sempre com números e fontes reais. |
A disponibilidade varia por ferramenta: a busca na web funciona em todos os modelos Sabiá, enquanto a execução de código e o Data Ocean estão disponíveis apenas no sabia-4-thinking. Todas vêm desligadas por padrão e são ativadas por requisição.
Como funciona
O fluxo é agêntico e roda inteiramente no servidor. Você não precisa orquestrar nada: o modelo cuida das chamadas intermediárias e devolve só o resultado. São três etapas:
- Sua requisição: você chama a API e liga as ferramentas que quiser, ou várias ao mesmo tempo.
- O trabalho no servidor: o Sabiá decide quais ferramentas usar e as executa em vários passos, internamente. O raciocínio e as chamadas intermediárias ficam internos.
- A resposta: a API devolve apenas a resposta final, já com as fontes citadas e os arquivos que tiverem sido gerados.
Como ativar
Você liga as flags na própria chamada, sempre com stream: false. Na biblioteca da OpenAI, elas vão no extra_body. No exemplo abaixo, a pergunta combina as duas: o Data Ocean para os dados oficiais e a busca na web para o que é mais recente.
Dá para combinar quantas ferramentas quiser (basta acrescentar code_execution para a terceira) e ainda usá-las com as suas próprias funções. Cada resposta também informa quantas execuções ocorreram, no campo usage.tool_execution_details. A documentação traz os exemplos com a Responses API e os formatos de retorno, em docs.maritaca.ai.
Ligar o data_ocean já ativa a busca na web e a execução de código automaticamente, porque as respostas do Data Ocean costumam cruzar dados oficiais com busca e cálculo.
O que dá para pedir
Alguns exemplos de pedido que cada ferramenta resolve sozinha, sem você precisar buscar o dado antes nem rodar nada do seu lado:
“Qual é a cotação atual do dólar e o que explica o movimento de hoje? Cite as fontes.”
“Analise esta planilha de vendas e gere um gráfico com a tendência mês a mês.”
“Compare a renda média e o número de empresas das três maiores cidades do interior de São Paulo.”
Preço
As execuções são cobradas por uso, somadas ao custo normal de tokens. Os valores reais consumidos vêm em usage.tool_execution_details em toda resposta. Como o data_ocean liga a busca na web e a execução de código junto, uma requisição com data_ocean pode ser cobrada pelas três ferramentas: Data Ocean, busca na web e execução de código.
| Ferramenta | Unidade | Preço |
|---|---|---|
| Busca na web | por busca | R$ 0,0165 |
| Leitura de página | por página lida | R$ 0,066 |
| Data Ocean | por GB processado | R$ 0,10 |
| Execução de código | por minuto | R$ 0,016 |
Disponibilidade
As ferramentas integradas já estão disponíveis via API. A busca na web funciona em todos os modelos Sabiá; a execução de código e o Data Ocean estão disponíveis apenas no sabia-4-thinking. A documentação traz os exemplos completos, a Responses API e os formatos de retorno, em docs.maritaca.ai.