Tools¶

A Responses API do Nodexa suporta vários tipos de tools que permitem aos assistants ir além da geração de texto. Esta página descreve cada tool suportada, quando usar cada uma e quais provedores de LLM são compatíveis.

Como as Tools Funcionam¶

As tools são declaradas no array tools da sua request. O assistant decide quais tools invocar com base no contexto da conversa.

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "What is the weather in Tokyo right now?",
  "tools": [
    {
      "type": "web_search_preview"
    }
  ]
}

Tools explícitas substituem as tools configuradas

Se você incluir um array tools na sua request (mesmo um array vazio []), ele substitui as tools configuradas no assistant para aquela request. Para usar as tools padrão do assistant, omita o campo tools completamente.

Confira Precedência de Tools para detalhes.

Tipos de Tools¶

Function Tools (executadas pelo cliente)¶

As function tools permitem que você defina operações customizadas que rodam na sua aplicação. O assistant decide quando chamá-las, gera os argumentos e aguarda você executar a função e retornar o resultado.

{
  "type": "function",
  "name": "get_weather",
  "description": "Get the current weather for a given location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or coordinates, e.g. 'San Francisco' or '37.7749,-122.4194'"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature unit"
      }
    },
    "required": ["location"]
  }
}

Campo	Obrigatório	Tipo	Descrição
`type`	Sim	`"function"`	Identifica esta como uma function tool executada pelo cliente
`name`	Sim	`string`	Nome da função — apenas alfanumérico, underscores e hífens; máx 64 caracteres
`description`	Não	`string`	Descreve o que a função faz; ajuda o modelo a decidir quando chamá-la
`parameters`	Não	`object`	JSON Schema para os argumentos da função

Restrições:

Máximo de 128 function tools por request
Nomes de tools devem ser únicos dentro da request
Nomes devem corresponder a /^[a-zA-Z0-9_-]{1,64}$/

Confira Function Calling para o fluxo de execução completo.

Busca na Web — OpenAI (`web_search_preview`)¶

Usa a capacidade de busca na web embutida da OpenAI. Disponível para modelos da família gpt-4o com suporte a busca.

{
  "type": "web_search_preview",
  "search_context_size": "medium"
}

Campo	Obrigatório	Tipo	Descrição
`type`	Sim	`"web_search_preview"`	Identificador da tool de busca na web da OpenAI
`search_context_size`	Não	`"low" \\| "medium" \\| "high"`	Controla quanto contexto de busca é recuperado. Padrão: `"medium"`

Valores de search_context_size:

Valor	Descrição	Caso de Uso
`"low"`	Menos resultados, mais rápido	Consultas factuais simples
`"medium"`	Resultados balanceados	Uso geral (padrão)
`"high"`	Mais resultados, mais lento	Pesquisas complexas que precisam de cobertura ampla

Busca na Web — Claude (`web_search`)¶

Usa a capacidade de busca na web embutida do Anthropic Claude. Disponível para modelos Claude que suportam uso de tools.

{
  "type": "web_search",
  "allowed_domains": ["reuters.com", "bbc.co.uk", "apnews.com"],
  "blocked_domains": ["reddit.com", "twitter.com"]
}

Campo	Obrigatório	Tipo	Descrição
`type`	Sim	`"web_search"`	Identificador da tool de busca na web do Claude
`allowed_domains`	Não	`string[]`	Allowlist de domínios a incluir nos resultados
`blocked_domains`	Não	`string[]`	Blocklist de domínios a excluir dos resultados

Filtragem de domínio

Use allowed_domains quando quiser que o assistant cite apenas fontes confiáveis (por exemplo, sites de documentação oficial, grandes veículos de notícias). Use blocked_domains quando só algumas fontes precisam ser excluídas.

Google Search (`google_search`)¶

Usa o recurso Grounding with Google Search do Google via a API Gemini. Disponível para modelos Google Gemini.

{
  "type": "google_search",
  "dynamic_retrieval_threshold": 0.3
}

Campo	Obrigatório	Tipo	Descrição
`type`	Sim	`"google_search"`	Identificador da tool de busca/grounding do Google
`dynamic_retrieval_threshold`	Não	`number` (0.0–1.0)	Threshold de recuperação dinâmica. Valores menores = mais recuperação. Padrão: dependente do modelo

dynamic_retrieval_threshold:

O threshold controla com que frequência o grounding do Google é acionado com base na confiança do modelo de que dados atualizados da web são necessários.

Valor	Comportamento
`0.0`	Sempre buscar no Google Search
`0.3`	Buscar quando o modelo tiver incerteza moderada (bom default)
`1.0`	Buscar apenas quando o modelo tiver alta certeza de que precisa de dados em tempo real

Matriz de Compatibilidade por Provedor¶

Tipo de Tool	OpenAI (GPT-4o, etc.)	Anthropic (Claude)	Google (Gemini)
`function`	Sim	Sim	Sim
`web_search_preview`	Sim	Não	Não
`web_search`	Não	Sim	Não
`google_search`	Não	Não	Sim

Tool e modelo incompatíveis

Se você especificar uma tool não suportada pelo modelo do Agente Especialista ativo do assistant, a plataforma retorna um erro 400 com tool_not_supported_for_model. Combine o tipo de tool de busca na web com o modelo em uso, ou omita a tool de busca na web e deixe a configuração do assistant determinar qual usar.

Combinando Tipos de Tools¶

Você pode incluir múltiplos tipos de tools em uma única request. Por exemplo, uma function tool junto com uma tool de busca na web:

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "Look up today's USD/EUR exchange rate and calculate how much 250 USD is in EUR.",
  "tools": [
    {
      "type": "web_search_preview"
    },
    {
      "type": "function",
      "name": "calculate",
      "description": "Perform arithmetic calculations",
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string",
            "description": "A math expression to evaluate, e.g. '250 * 0.92'"
          }
        },
        "required": ["expression"]
      }
    }
  ]
}

O assistant pode chamar a tool de busca na web primeiro para obter a taxa de câmbio e depois chamar calculate com o valor recuperado.

Tools Configuradas no Assistant¶

O administrador da sua plataforma configura tools em cada assistant no painel administrativo do Nodexa. Elas podem incluir:

Integrações com APIs REST
Conexões com servidores MCP (Model Context Protocol)
Recuperação de base de conhecimento
Busca na web

Quando você omite o campo tools, essas tools configuradas ficam automaticamente disponíveis para o assistant. Confira Precedência de Tools para entender como as tools em nível de request e em nível de assistant interagem.

Limites de Tools¶

Limite	Valor
Máximo de tools por request	128
Comprimento máximo do nome da tool	64 caracteres
Caracteres permitidos no nome	Alfanumérico, `_`, `-` apenas
Nomes de tools devem ser únicos	Sim (dentro de uma única request)

Confira Limites para a referência completa de limites.