Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Busca no X (Twitter)

A ferramenta x_search permite ao agente buscar posts, perfis e threads do X (Twitter) diretamente. Ela é apoiada na ferramenta x_search embutida da xAI, na API Responses em https://api.x.ai/v1/responses — o próprio Grok executa a busca no servidor e devolve resultados sintetizados, com citações aos posts de origem.

Use isto em vez do web_search quando você quiser especificamente discussão atual, reações ou afirmações no X. Para páginas web em geral, continue com web_search / web_extract.

x_search vs xurl​

O Hermes pode expor duas superfícies diferentes do X:

SuperfícieUse paraNão use para
x_searchDescoberta pública do X somente leitura: discussão atual, reações, afirmações, perfis, threads e respostas sintetizadas com citações.Postar, responder, curtir, DMs, envio de mídia, apagar, ou provar que uma conta autenticada do X mudou de estado.
skill xurlTrabalho exato ou autenticado na API do X: post, reply, read, like, dm, timelines, menções, envio de mídia, leituras específicas de conta e endpoints v2 crus.Pesquisa pública ampla no X sintetizada pelo Grok, quando o x_search está disponível e nenhum contexto de conta autenticada é necessário.

Para fluxos mistos, use o x_search para descobrir posts públicos candidatos e então mude para xurl read ou outro comando exato do xurl depois que o post/usuário/ação alvo estiver claro. Qualquer ação no X que mude estado precisa ser confirmada pela saída do xurl ou pela resposta da API do X; uma resposta do x_search nunca é evidência de que uma escrita aconteceu.

dica

Se você já paga o Portal por um modelo da xAI de qualquer jeito, as chamadas do Live Search são cobradas na mesma chave xAI configurada para conversa. Veja Nous Portal.

Autenticação​

O x_search se registra quando qualquer um dos caminhos de credencial da xAI está disponível:

CredencialOrigemConfiguração
OAuth de SuperGrok / X Premium+Login no navegador em accounts.x.ai, renovado automaticamentehermes auth add xai-oauth — veja xAI Grok OAuth (SuperGrok / X Premium+)
XAI_API_KEY (preferida)Chave paga da API da xAIDefina em ~/.hermes/.env

Os dois batem no mesmo endpoint com a mesma carga — a única diferença é o token bearer. Quando os dois estão configurados, a XAI_API_KEY explícita vence — o bearer OAuth da assinatura autoriza /v1/responses, mas responde ao x_search num modo explicativo degradado do Grok, sem citações, enquanto a chave de API devolve posts de verdade. Repare que isso significa que o x_search roda com cobrança medida de API quando há uma chave definida; remova a XAI_API_KEY para voltar à cota da sua assinatura (com a ressalva da resposta degradada).

O check_fn da ferramenta roda o resolvedor de credenciais da xAI toda vez que a lista de ferramentas do modelo é remontada. Um retorno True significa que o bearer é obtenível E não vazio E (se estivesse expirado) foi renovado com sucesso. Tokens revogados com renovação falha escondem a ferramenta do esquema; o modelo simplesmente não consegue vê-la.

Habilitar a ferramenta​

Liga sozinha quando há credenciais da xAI (token OAuth ou XAI_API_KEY). Desligue explicitamente por hermes tools → Search → x_search se você não quiser isso.

hermes tools
# → 🐦 X (Twitter) Search   (aperte espaço para ligar)

O seletor oferece duas opções de credencial:

  1. xAI Grok OAuth (SuperGrok / Premium+) — abre o navegador em accounts.x.ai se você ainda não estiver logado
  2. xAI API key — pede a XAI_API_KEY

Qualquer das duas satisfaz a exigência. Você pode escolher a credencial que já tiver; a ferramenta funciona igual com as duas. Se as duas acabarem configuradas, o OAuth é preferido na hora da chamada.

Configuração​

# ~/.hermes/config.yaml
x_search:
  # Modelo da xAI usado na chamada Responses.
  # grok-4.5 é o padrão recomendado; qualquer modelo Grok
  # com acesso à ferramenta x_search funciona.
  model: grok-4.5

  # Esforço de raciocínio opcional: low, medium, high ou xhigh. Quando omitido,
  # vale o padrão do modelo selecionado. xhigh só é suportado por
  # modelos que o documentam, como o grok-4.20-multi-agent.
  # reasoning_effort: low

  # Tempo limite da requisição em segundos. O x_search pode levar de 60 a 120s em
  # consultas complexas — o padrão é generoso. Mínimo: 30.
  timeout_seconds: 180

  # Número de tentativas automáticas em 5xx / ReadTimeout / ConnectionError.
  # Cada tentativa recua um pouco (1,5x segundos por tentativa, com teto de 5s).
  retries: 2

O reasoning_effort é enviado à API Responses da xAI como reasoning: {effort: ...}. Deixe sem definir em modelos que não suportam raciocínio configurável. Valores inválidos falham antes de qualquer requisição à API.

Parâmetros da ferramenta​

O agente chama o x_search com estes argumentos:

ParâmetroTipoDescrição
querystring (obrigatório)O que procurar no X.
allowed_x_handlesarray de stringsLista opcional de perfis a incluir exclusivamente (máximo 10). O @ inicial é removido.
excluded_x_handlesarray de stringsLista opcional de perfis a excluir (máximo 10). Mutuamente exclusiva com allowed_x_handles.
from_datestringData inicial opcional em YYYY-MM-DD.
to_datestringData final opcional em YYYY-MM-DD.
enable_image_understandingbooleanPede à xAI que analise as imagens anexadas aos posts encontrados.
enable_video_understandingbooleanPede à xAI que analise os vídeos anexados aos posts encontrados.

A ferramenta devolve um JSON com:

  • answer — resposta em texto sintetizada pelo Grok
  • citations — citações devolvidas pelo campo de nível superior da API Responses
  • inline_citations — anotações url_citation extraídas do corpo da mensagem (cada uma com url, title, start_index, end_index)
  • degraded — true quando algum filtro de estreitamento (allowed_x_handles, excluded_x_handles, from_date, to_date) foi definido E os dois canais de citação voltaram vazios. Nesse caso a answer foi sintetizada do conhecimento próprio do modelo, e não do índice do X, então trate-a como sem fonte. false no restante (inclusive no caso "nenhum filtro definido" — uma resposta ampla sem fonte é só uma resposta, não um filtro que errou)
  • degraded_reason — string curta nomeando quais filtros estavam ativos, ou null quando degraded é false
  • credential_source — "xai-oauth" se o OAuth resolveu, "xai" se a chave de API resolveu
  • model, query, provider, tool, success

Validação de datas​

from_date / to_date são validadas no cliente antes da chamada HTTP:

  • As duas, se fornecidas, precisam ser interpretáveis como YYYY-MM-DD.
  • Quando as duas estão definidas, from_date precisa ser igual ou anterior a to_date.
  • from_date não pode ser posterior a hoje em UTC — nenhum post pode existir numa janela que ainda não começou, então a chamada devolveria zero citações com certeza.
  • to_date no futuro é permitida (quem chama pode legitimamente pedir "de ontem até amanhã" para pegar posts conforme eles chegam).

Falhas de validação aparecem como um resultado de ferramenta estruturado {"error": "..."}, nunca como uma chamada HTTP à xAI.

Exemplo​

Conversando com o agente:

O que as pessoas no X estão dizendo sobre os novos recursos de imagem do Grok? Foque nas respostas de @xai.

O agente vai:

  1. Chamar x_search com query="reactions to new Grok image features", allowed_x_handles=["xai"]
  2. Receber de volta uma resposta sintetizada mais uma lista de citações apontando para posts específicos
  3. Responder com a resposta e as referências

Se o pedido seguinte do usuário for "responda o melhor" ou "curta esse post", o agente deve mudar para a skill xurl, confirmar o post alvo exato e usar a ação da API do X. O x_search continua sendo uma ferramenta de descoberta.

Resolução de problemas​

"No xAI credentials available"​

A ferramenta mostra isso quando os dois caminhos de autenticação falham. Defina XAI_API_KEY em ~/.hermes/.env ou rode hermes auth add xai-oauth e complete o login no navegador. Depois reinicie a sua sessão para o agente reler o registro de ferramentas.

"x_search is not enabled for this model"​

O x_search.model configurado não tem acesso à ferramenta x_search do lado do servidor. Mude para grok-4.5 (o padrão) ou outro modelo Grok que a suporte. Confira a documentação da xAI para a lista atual.

A ferramenta não aparece no esquema​

Duas causas possíveis:

  1. Conjunto de ferramentas não habilitado. Rode hermes tools e confirme que 🐦 X (Twitter) Search está marcado.
  2. Sem credenciais da xAI. O check_fn devolve False, então o esquema fica escondido. Rode hermes auth status para confirmar o estado do login xai-oauth, e verifique se a XAI_API_KEY está definida (se você usa o caminho por chave de API).

degraded: true — resposta sem citações​

Quando você usou allowed_x_handles, excluded_x_handles ou um intervalo de datas e a resposta volta com degraded: true, o índice do X da xAI não devolveu nenhum post correspondente, mas o Grok ainda produziu uma resposta sintetizada com os dados de treino dele. A resposta é sem fonte — não a trate como um resultado real do X.

Causas que vale conferir:

  • Erro de digitação no perfil. Tire o @, confira a grafia e confirme que a conta existe.
  • Intervalo de datas estreito demais ou passando dos posts de hoje; amplie e tente de novo.
  • Falha no índice da xAI. Algumas contas ativas intermitentemente não aparecem no x_search mesmo postando com regularidade. Tente de novo depois de alguns minutos, ou use a skill xurl para leituras diretas na API do X quando você precisar da timeline de um perfil exato.

Veja também​