Precedência de Tools¶

Os assistants do Nodexa possuem tools configuradas no painel administrativo. Você também pode passar tools na sua request à API. Esta página explica como essas duas fontes interagem e qual o conjunto efetivo de tools para cada request.

Duas Fontes de Tools¶

1. Tools configuradas no assistant (definidas pelo administrador do Nodexa)

São tools persistentes vinculadas ao assistant no painel administrativo. Podem incluir:

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

2. Tools em nível de request (fornecidas no campo tools da sua chamada à API)

São tools que você declara por request no array tools:

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "...",
  "tools": [
    { "type": "function", "name": "my_custom_tool", ... }
  ]
}

Regras de Precedência¶

Regra 1: Omitir `tools` → usar as tools configuradas no assistant¶

Se você não incluir um campo tools na sua request, o assistant usa suas tools configuradas sem alteração.

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "Search for recent news about AI."
}

Neste caso, se o assistant tiver uma tool de busca na web configurada, ela estará disponível.

Regra 2: Incluir `tools` → substituir as tools configuradas no assistant¶

Se você incluir um array tools — mesmo um array vazio — ele substitui as tools configuradas no assistant para aquela request. As tools configuradas no assistant não ficam disponíveis.

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "Search for recent news about AI.",
  "tools": []
}

Neste caso, o assistant não tem nenhuma tool disponível — mesmo que busca na web esteja configurada no painel administrativo. O assistant vai responder apenas com base no conhecimento de treinamento dele.

{
  "model": "YOUR_ASSISTANT_ID",
  "input": "Check the weather and search my calendar.",
  "tools": [
    { "type": "function", "name": "get_weather", ... }
  ]
}

Neste caso, apenas get_weather está disponível. As tools de calendário configuradas no painel administrativo não estão.

Tabela Resumo¶

Campo `tools` na request	Conjunto efetivo de tools
Omitido	Tools configuradas no assistant
`[]` (array vazio)	Nenhuma tool disponível
`[tool1, tool2]`	Apenas `tool1` e `tool2`

Padrões Comuns¶

Estender as tools do assistant com tools em nível de request¶

Atualmente não existe um comportamento de merge embutido. Se você quiser que o assistant tenha suas tools configuradas mais tools adicionais em nível de request, você precisa buscar a configuração de tools do assistant e incluir todas as tools explicitamente:

// Não suportado atualmente como um único campo — declare todas as tools de que precisa:
const response = await client.responses.create({
  model: assistantId,
  input: userMessage,
  tools: [
    // Tools configuradas pelo admin que você quer incluir
    { type: 'web_search_preview' },
    // Mais sua tool de função personalizada
    {
      type: 'function',
      name: 'lookup_order',
      description: 'Look up a customer order by order ID',
      parameters: {
        type: 'object',
        properties: {
          orderId: { type: 'string' },
        },
        required: ['orderId'],
      },
    },
  ],
});

Prefira omitir tools quando possível

Se sua integração não precisa adicionar function tools, omita tools completamente e deixe o assistant usar suas tools configuradas. Isso simplifica sua integração e mantém o gerenciamento de tools centralizado no painel administrativo.

Desabilitar todas as tools para uma request específica¶

Para obter uma resposta pura do LLM sem invocações de tools — útil para requests puramente conversacionais onde chamadas de tool seriam indesejadas — passe um array de tools vazio:

const response = await client.responses.create({
  model: assistantId,
  input: 'Write me a haiku about autumn.',
  tools: [], // Sem tools — escrita criativa não precisa de chamadas de tool
});

Usar apenas function tools do lado do cliente¶

Se você quiser que o assistant use apenas suas function tools (sem busca na web, sem base de conhecimento), passe apenas suas function tools:

const response = await client.responses.create({
  model: assistantId,
  input: userMessage,
  tools: [
    { type: 'function', name: 'get_account_balance', ... },
    { type: 'function', name: 'get_recent_transactions', ... },
  ],
});

Por Que Este Design?¶

O comportamento de substituição dá controle explícito sobre quais tools estão disponíveis em cada request:

Previsibilidade — você sabe exatamente quais tools estão disponíveis para cada request
Segurança — você pode impedir que o assistant chame serviços externos em requests sensíveis
Flexibilidade — diferentes partes da sua aplicação podem usar o mesmo assistant com configurações de tools diferentes

O trade-off é que, se você quiser adicionar function tools mantendo as tools configuradas no assistant, precisa declarar todas as tools explicitamente. Isso é intencional: evita interações sutis entre tools configuradas pelo admin e tools em nível de request.