Tavily

Visão geral

Tavily é uma plataforma de busca e recuperação de informações construída para agentes de IA. Ela oferece endpoints especializados para pesquisa na web, extração de conteúdo de páginas, rastreamento em profundidade de sites e mapeamento de estruturas de URL — tudo com controles precisos de profundidade, domínio e formato. Com a integração Tavily no SquadOS, seus agentes ganham acesso a informações atualizadas da web sem a complexidade de gerenciar scrapers, proxies ou limites de taxa.

• Site oficial: https://tavily.com/
• Documentação na Composio: docs.composio.dev/toolkits/tavily

Autenticação

Esta ferramenta utiliza chave de API (API_KEY) para conectar.

Você vai precisar dos seguintes campos:

Campo	Obrigatório	Descrição
api_key	Sim	Chave de API gerada no painel Tavily em app.tavily.com, usada para autenticar todas as requisições.

Como obter a credencial

1. Acesse app.tavily.com/home e crie uma conta (ou faça login se já tiver uma).
2. No painel, localize a seção API Keys.
3. Clique no botão ”+” ao lado da seção de API Keys para gerar uma nova chave.
4. Preencha um nome para a chave, escolha o tipo (Development para até 100 req/min; Production para até 1.000 req/min) e defina um limite mensal opcional de créditos.
5. Copie a chave gerada — esse é o valor a usar no campo api_key ao conectar no SquadOS.

Dica

Toda conta nova começa com 1.000 créditos gratuitos por mês, sem cartão de crédito. Use uma chave dedicada para o SquadOS para facilitar o monitoramento de uso e a revogação individual.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por Tavily.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde informa a chave de API obtida acima.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Ações disponíveis

Rastrear site

TAVILY_CRAWL

Realiza rastreamento inteligente de sites com exploração paralela de caminhos e extração de conteúdo. Use quando precisar percorrer e extrair conteúdo de múltiplas páginas de um site seguindo padrões específicos ou instruções em linguagem natural. Suporta controles de profundidade e abrangência, filtragem por domínio e instruções para rastreamento guiado.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
url	string	Sim	URL raiz para iniciar o rastreamento. Pode ser fornecida com ou sem protocolo (ex.: docs.tavily.com ou https://docs.tavily.com).
limit	integer	Não	Total de links a processar antes de encerrar o rastreamento.
format	string ("markdown" | "text")	Não	Formato do conteúdo extraído: "markdown" ou "text".
timeout	integer	Não	Tempo máximo de espera em segundos para a operação de rastreamento. Intervalo: 10–150.
max_depth	integer	Não	Profundidade máxima de rastreamento a partir da URL base. Intervalo: 1–5. Profundidade 1 significa apenas links diretos da URL raiz.
max_breadth	integer	Não	Número máximo de links a seguir por nível de página.
instructions	string	Não	Instruções em linguagem natural para guiar o rastreador a encontrar páginas ou conteúdos específicos. Usar instruções aumenta o custo para 2 créditos por 10 páginas. Exemplo: "Find all pages about the Python SDK".
select_paths	array	Não	Lista de padrões regex para caminhos de URL específicos a incluir. Exemplo: ['/docs/.*', '/api/.*'].
exclude_paths	array	Não	Lista de padrões regex para caminhos de URL a ignorar. Exemplo: ['/admin/.*', '/private/.*'].
extract_depth	string ("basic" | "advanced")	Não	Nível de extração: "basic" para extração padrão ou "advanced" para análise mais profunda.
include_usage	boolean	Não	Se verdadeiro, inclui informações de uso de créditos na resposta.
allow_external	boolean	Não	Se verdadeiro, inclui links para domínios externos no rastreamento.
include_images	boolean	Não	Se verdadeiro, inclui imagens nos resultados do rastreamento.
select_domains	array	Não	Lista de padrões regex para filtragem de domínios. Apenas URLs que correspondam a esses padrões serão rastreadas.
exclude_domains	array	Não	Lista de padrões regex para excluir determinados domínios do rastreamento.
include_favicon	boolean	Não	Se verdadeiro, inclui as URLs dos favicons nos resultados.
chunks_per_source	integer	Não	Número máximo de trechos de conteúdo por fonte (máx. 500 caracteres cada). Intervalo: 1–5.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Extrair conteúdo de páginas

TAVILY_EXTRACT

Extrai e analisa o conteúdo de páginas web a partir de URLs especificadas usando o endpoint de extração do Tavily. Use quando precisar recuperar conteúdo limpo e estruturado de páginas, com extração opcional de imagens e reordenação de trechos por relevância em relação a uma consulta.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
urls	string	Sim	URL(s) da(s) qual(is) extrair conteúdo. Pode ser uma única URL ou uma lista de URLs.
query	string	Não	Intenção do usuário para reordenação dos trechos extraídos. Ajuda a priorizar o conteúdo mais relevante com base na consulta.
format	string ("markdown" | "text")	Não	Formato do conteúdo extraído: "markdown" ou "text". Padrão: "markdown".
timeout	number	Não	Tempo máximo de espera em segundos para a requisição de extração. Deve estar entre 1,0 e 60,0 segundos. Padrão: 30,0.
extract_depth	string ("basic" | "advanced")	Não	Nível de extração: "basic" para extração padrão ou "advanced" para extração mais aprofundada. Padrão: "basic".
include_usage	boolean	Não	Se verdadeiro, inclui informações de uso de créditos na resposta.
include_images	boolean	Não	Se verdadeiro, inclui uma lista de URLs de imagens encontradas no conteúdo extraído.
include_favicon	boolean	Não	Se verdadeiro, inclui a URL do favicon para cada resultado.
chunks_per_source	integer	Não	Número máximo de trechos relevantes a extrair por fonte. Deve estar entre 1 e 5. Padrão: 3.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Consultar uso da conta

TAVILY_GET_USAGE

Recupera as estatísticas de uso da chave de API e da conta Tavily. Use quando precisar verificar o consumo de créditos, limites e uso por endpoint para as operações de busca, extração, rastreamento, mapeamento e pesquisa aprofundada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Mapear site

TAVILY_MAP

Mapeia um site e descobre suas páginas. Use quando precisar escanear um site e obter uma lista estruturada de URLs que ele contém, sem extrair o conteúdo completo de cada página.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
url	string	Sim	URL raiz para iniciar o mapeamento (ex.: docs.tavily.com). É o ponto de partida a partir do qual o rastreador descobre e mapeia as páginas.
limit	integer	Não	Total de links a processar antes de encerrar. Mínimo: 1. Padrão: 50.
timeout	integer	Não	Número máximo de segundos a aguardar para concluir o mapeamento. Intervalo: 10–150. Padrão: 150.
max_depth	integer	Não	Quão longe da URL base o rastreador explora. Intervalo: 1–5. Padrão: 1.
max_breadth	integer	Não	Número de links a seguir por nível de página. Mínimo: 1. Padrão: 20.
instructions	string	Não	Instruções em linguagem natural para guiar a exploração do rastreador. Usar este parâmetro aumenta o custo para 2 créditos por 10 páginas, em vez de 1.
select_paths	array	Não	Lista de padrões regex para caminhos de URL específicos a incluir (ex.: '/docs/.*' para incluir apenas caminhos de documentação).
exclude_paths	array	Não	Lista de padrões regex para ignorar certos caminhos de URL (ex.: '/admin/.*' para excluir páginas administrativas).
include_usage	boolean	Não	Se verdadeiro, inclui detalhes de uso de créditos na resposta. Padrão: falso.
allow_external	boolean	Não	Se verdadeiro, inclui links externos nos resultados. Padrão: verdadeiro.
select_domains	array	Não	Lista de padrões regex para segmentação de domínios. Apenas URLs que correspondam a esses padrões serão incluídas.
exclude_domains	array	Não	Lista de padrões regex para excluir determinados domínios dos resultados do mapeamento.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Buscar na web

TAVILY_SEARCH

Realiza uma busca na web via API do Tavily, com controles para profundidade de busca, tipos de conteúdo, quantidade de resultados e filtragem por domínio. Requer uma conexão Tavily ativa (401 indica falha de autenticação). Limite de taxa: ~2 req/s; aplique backoff exponencial em respostas HTTP 429. Os resultados estão aninhados em response_data.results (não é uma lista plana).

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
query	string	Sim	String de consulta para encontrar informações relevantes na web. Não existe filtro de data nativo; incorpore indicadores de tempo diretamente na string de consulta. Para maior abrangência, faça múltiplas consultas focadas em vez de uma consulta ampla.
max_results	integer	Não	Número máximo de resultados de busca a retornar. Valores altos combinados com include_raw_content=true geram payloads muito grandes.
search_depth	string ("basic" | "advanced")	Não	Profundidade da busca: "basic" (padrão, 1 crédito de API) ou "advanced" (aprofundada, 2 créditos de API).
include_answer	boolean	Não	Se verdadeiro, tenta incluir uma resposta direta à consulta (adequado para perguntas factuais). O campo answer pode ser nulo; use response_data.results como evidência primária.
include_images	boolean	Não	Se verdadeiro, inclui links para imagens relevantes nos resultados.
exclude_domains	array	Não	Lista de domínios (ex.: ['exclude.com', 'othersite.net']) a excluir dos resultados; resultados desses domínios serão filtrados.
include_domains	array	Não	Lista de domínios específicos (ex.: ['example.com', 'website.org']) para restringir a busca; apenas resultados desses domínios são retornados.
include_raw_content	boolean	Não	Se verdadeiro, inclui o conteúdo bruto dos sites visitados (ex.: HTML ou texto não processado). Sem isso, os resultados podem ser trechos curtos que omitem detalhes importantes.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.