> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apollospace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavily — busca web

> O motor de busca pública por trás do Scout — buscas grounded com citação por URL.

Você pergunta ao pesquisador do time: "o que o concorrente acabou de anunciar?" Um minuto depois você tem a resposta — com os links de fonte por trás de cada linha, não um chute confiante a partir de treino desatualizado. Esse pesquisador é o [Scout](/pt/agents/scout), alcançando a web ao vivo em nome da org, e o Tavily é o motor com que ele busca.

O que isso tira do seu colo: ninguém precisa abrir dez abas, ler por cima e colar links de volta num doc. A busca, a leitura e a citação acontecem por você.

## O que é

[Tavily](https://tavily.com) é um motor de busca **construído para
agentes de IA**. Diferente de uma API genérica de busca, o Tavily
retorna snippets já estruturados pra grounding: cada resultado vem
com URL fonte, score de relevância e snippet de contexto.

O [Scout](/pt/agents/scout) usa o Tavily como motor primário em toda
busca pública.

## Por que Tavily (e não algo "mais simples")

| Alternativa                    | Por que NÃO é o default                                        |
| ------------------------------ | -------------------------------------------------------------- |
| Google search direto           | Sem API pública estável + termos de uso restritivos            |
| Web scraping genérico          | Frágil, custoso, alto risco de bloqueio                        |
| Bing Search API                | Funciona, mas Tavily entrega resultados melhor curados pra LLM |
| Busca web nativa da plataforma | É usado como **fallback** quando Tavily não está disponível    |

## Conexão (BYO key)

A integração é **Bring Your Own Key**:

<Steps>
  <Step title="Crie conta no Tavily">
    [tavily.com](https://tavily.com) → free tier cobre testes iniciais.
    Planos pagos pra volume maior.
  </Step>

  <Step title="Pegue a API key">
    No dashboard do Tavily, copie sua API key.
  </Step>

  <Step title="Cole no Apollo Space">
    **Settings → Integrações → Tavily** → cola a key.
  </Step>

  <Step title="Pronto">
    O Scout passa a usar essa key automaticamente. Você pode trocar
    ou revogar a qualquer momento.
  </Step>
</Steps>

<Info>
  A key é guardada **criptografada** e isolada por organização — outro
  cliente Apollo Space não vê sua key. Veja [Segurança](/pt/trust/security).
</Info>

## Tier de busca

O Tavily expõe dois tiers de busca:

| Tier         | O que entrega                                                     | Quando faz sentido                     |
| ------------ | ----------------------------------------------------------------- | -------------------------------------- |
| **Basic**    | Resposta rápida, snippets curtos                                  | Pesquisa exploratória, queries simples |
| **Advanced** | Conteúdo mais profundo + chunks maiores + processamento adicional | Análise crítica, fact-checking         |

O Scout usa o tier **basic** por default (boa relação custo/qualidade
pro caso de uso típico). Times com necessidade específica podem
configurar advanced via suporte.

## Fallback automático

Se a busca pelo Tavily falha (chave não configurada, rate limit
externo da Tavily, erro de rede), o Scout **cai automaticamente** pro
busca web nativa da plataforma — você não vê interrupção, só uma
nota no trace indicando o fallback foi usado.

## Cap por org

Pra proteger sua chave Tavily de exhaust acidental (loop de buscas em
debugging, agente mal configurado), o Apollo Space aplica um **cap interno
de buscas-por-segundo por organização**.

Quando o cap dispara:

1. A busca atual cai pro fallback nativo por um período curto
2. O cap-fire fica registrado no histórico de eventos da org
3. Após o cooldown, o Tavily volta a ser usado normalmente

Isto é **independente** dos rate limits da própria Tavily — é uma
proteção em camada extra que o Apollo Space dá em cima da sua chave.

## Modo dry-run pra desenvolvimento

Em ambientes de teste/dev, o Apollo Space opera por default em **dry-run**:
o Scout retorna 3 snippets canned (com URLs claramente marcadas como
`example.com`) sem realmente chamar a Tavily.

Isso protege sua chave de queima em ambientes que não são produção.
Em produção o dry-run vem desligado por default.

## Custos

| Onde cai                                                     | Quem paga                               |
| ------------------------------------------------------------ | --------------------------------------- |
| **Busca Tavily** (por chamada à API)                         | Sua conta Tavily direto                 |
| **Orquestração do Scout** (LLM + processamento Apollo Space) | Seu saldo de [Stars](/pt/billing/stars) |

A fatura Tavily vai pra você diretamente — Apollo Space não intermedia
pagamento.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Scout — quem usa Tavily" icon="binoculars" href="/pt/agents/scout">
    A persona que dispara as buscas.
  </Card>

  <Card title="Stars" icon="star" href="/pt/billing/stars">
    Como o uso do Scout (orquestração) entra no faturamento.
  </Card>

  <Card title="Apify (enrichment)" icon="map-pin" href="/pt/integrations/apify">
    Pra busca em Google Maps + enrichment de site, o Apollo Space usa
    Apify, não Tavily.
  </Card>
</CardGroup>