Nota do autor: a partir de uma única frase dita ao Agent, instalamos o Agent-Reach passo a passo, fazendo com que Claude Code, Codex e outros Agents leiam notas do Xiaohongshu, posts do X e legendas do Bilibili — com tabela de canais, comparação de comandos, solução de problemas e estimativa de custos.
Quando você pede ao Agent para fazer uma pesquisa de concorrência, ele logo bate num limite. Se você diz “dá uma olhada no que o pessoal está falando sobre esse fone no Xiaohongshu”, a busca web nativa só devolve uns poucos artigos repostados — as notas do Xiaohongshu em si não aparecem de jeito nenhum. Se você diz “resume o que essa conta do X publicou nesta semana”, ele não consegue abrir a linha do tempo que fica atrás do login.
Com conteúdo em vídeo é pior ainda. Numa apresentação técnica de 40 minutos no Bilibili, a informação realmente valiosa está na narração falada. A busca genérica não pega legendas do Bilibili, então o Agent só pode chutar a partir do título e da descrição. Plataformas chinesas como Xueqiu e V2EX também têm cobertura péssima na busca genérica, e as páginas que voltam vêm cheias de menus de navegação e anúncios.
É exatamente esse problema que o projeto open source Agent-Reach resolve. Ele já tem mais de 100 mil estrelas no GitHub e se posiciona como “fazer o AI Agent alcançar a internet que ele mesmo não consegue acessar”. Não é mais uma ferramenta em que você precisa decorar comandos de terminal: a linha principal deste tutorial é concluir a instalação dizendo uma frase ao Agent, e depois disso adicionar canais, trocar de conta e atualizar também se faz com linguagem natural.
Valor central: ao terminar a leitura, seu Agent vai conseguir ler conteúdo do X, Reddit, Bilibili, Xiaohongshu e outras plataformas, e você vai saber claramente como validar cada etapa, como investigar erros e quanto custa mais ou menos uma pesquisa.
Principais pontos do tutorial do Agent-Reach
Antes de colocar a mão na massa, vale organizar os fatos essenciais do Agent-Reach em uma tabela. As informações abaixo se baseiam na verificação feita no repositório do projeto em 2026-10-26.
| Ponto | Descrição | O que isso significa para você |
|---|---|---|
| Popularidade do projeto | Mais de 100 mil stars, já chegou ao 1º lugar do Trendshift GitHub Trending no dia | Comunidade ativa, tem gente acompanhando as issues |
| Licença e ambiente | Open source sob MIT, escrito em Python 3.10+ | Uso gratuito e código que você mesmo pode auditar |
| Custo da plataforma | É gratuito por si só, não exige nenhuma taxa de API da plataforma | O custo real é apenas o token do modelo do Agent |
| Modo de funcionamento | Somente leitura: apenas busca e lê, não publica, não comenta, não curte, não manda DM | Ele não vai “falar” por você nas plataformas |
| Formato de saída | Da versão 1.6 em diante, cada comando retorna um objeto JSON | Basta o Agent ler ok / result / error.hint para saber se deu certo |
As quatro categorias de “inacessíveis” que o Agent-Reach resolve
Agentes de CLI como Claude Code, Codex, Hermes Agent e OpenClaw já vêm com busca e leitura de páginas web, mas existem quatro tipos de conteúdo que eles simplesmente não alcançam. O primeiro são funcionalidades que exigem login, como buscar notas no Xiaohongshu, conferir a atividade de uma conta no X ou ler os detalhes de uma vaga.
O segundo é o conteúdo dentro de vídeos, incluindo as legendas do Bilibili e do YouTube, além da transcrição de áudio de vídeos do YouTube e de episódios do podcast Xiaoyuzhou.
O terceiro são as plataformas chinesas: Bilibili, Xiaohongshu, V2EX e Xueqiu têm uma cobertura muito ruim nas buscas genéricas. O quarto são dados estruturados e limpos, como as cotações do Xueqiu, posts e respostas do V2EX, e repositórios e issues do GitHub. O que o Agent-Reach devolve é conteúdo já organizado, e não uma página HTML inteira — isso reduz diretamente os tokens que o Agent consome.
A lógica de design do Agent-Reach: principal mais alternativa
O Agent-Reach trata cada ação em cada plataforma como uma “lista de ferramentas a serem tentadas em ordem”. Por exemplo, para ler um vídeo do Bilibili ele usa primeiro o bili-cli e, se falhar, troca automaticamente para a interface pública do Bilibili; para ler uma página web, usa primeiro o Jina Reader e depois o Exa. Mudanças de layout nas plataformas e ferramentas que param de funcionar são o normal, então os mantenedores só precisam ajustar essa lista — a forma como você e o Agent usam continua exatamente igual.
Quais canais o Agent-Reach suporta
A versão atual organiza os canais em três níveis: os canais padrão já vêm prontos para uso após a instalação; os canais opcionais são ativados com um simples pedido ao Agent — algo como “me adiciona o XX” — e o software necessário é instalado automaticamente; os canais experimentais funcionam, mas enfrentam uma proteção anti-scraping mais rígida das plataformas e podem parar de funcionar a qualquer momento. Vale salvar a tabela abaixo, porque ela responde às duas perguntas mais comuns: “o que dá para fazer” e “do que eu preciso”.
| Canal | Nível | O que faz | O que precisa |
|---|---|---|---|
| bilibili | Padrão | Busca, informações de vídeo, populares, legendas | Legendas exigem login via QR code |
| v2ex | Padrão | Populares, nodes, posts e respostas, usuários | Não precisa de login |
| github | Padrão | Buscar repositórios, ler repositórios e README, ler issues e PRs (com comentários) | Não precisa de login |
| youtube | Padrão | Informações de vídeo, busca, legendas, transcrição de áudio | Transcrição exige chave Groq ou OpenAI |
| web | Padrão | Busca na web, leitura de páginas (canal de reserva) | Não precisa de login |
| xiaohongshu | Opcional | Buscar notas, ler o conteúdo, ver comentários | Precisa de login |
| xueqiu | Opcional | Cotações em tempo real, buscar ações, posts em alta, ações em alta | Cotações não precisam de login; posts e ações em alta exigem login |
| boss | Opcional | Buscar vagas e descrições de cargo (JD) | Precisa de login |
| xiaoyuzhou | Opcional | Transcrição de podcast em texto | Precisa de chave Groq |
| Opcional | Buscar vagas, ler detalhes da vaga | Vagas públicas não precisam de login; busca interna exige login | |
| Opcional | Buscar posts, ler o conteúdo, ver comentários, ver comunidades | Precisa de login | |
| twitter (X) | Experimental | Buscar tweets, perfil de usuário, tweets do usuário, ler threads | Precisa de login |
| Experimental | Busca, informações de página | Precisa de login | |
| Experimental | Buscar usuários, perfil, posts do usuário | Precisa de login |
Um ponto que vale destacar: os canais padrão podem ser removidos se você não quiser usá-los, e depois de removidos eles não voltam automaticamente nas próximas atualizações. O X mencionado no título está atualmente entre os canais experimentais — serve para consultas ocasionais, mas não é uma fonte de dados estável para depender todos os dias.
Agent-Reach: primeiros passos rápidos — basta dizer uma frase ao Agent
Todo o processo de instalação não exige que você abra o terminal. Cada etapa abaixo traz um “critério de validação”: confirme que passou antes de seguir para a próxima e, se algo der errado, consulte direto a tabela de solução de problemas mais adiante no texto.
Etapa 1: ative “Permitir execução de comandos” nas configurações do Agent
O Agent-Reach precisa que o Agent consiga executar comandos de terminal. Na interface gráfica de configurações do Agent que você usa, procure um botão no estilo “Permitir execução de comandos” e ative. Cada Agent dá um nome um pouco diferente. Se não tiver uv no computador, não se preocupe: o Agent instala o uv automaticamente antes, com apenas um comando e sem precisar de senha de administrador.
- Critério de validação: diga ao Agent “me diga em qual diretório você está agora”. O esperado é que ele realmente execute o comando e retorne um caminho, em vez de responder “não consigo executar comandos”.
Passo 2: Enviar o comando de instalação para o Agent
Essa é a forma mais prática e a oficialmente recomendada. Basta copiar a frase abaixo e mandar para o Agent:
Me ajude a instalar o Agent Reach: https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/install.md
Depois de ler as instruções de instalação, o Agent faz duas coisas sozinho: primeiro executa uv tool install https://github.com/Panniantong/Agent-Reach/releases/latest/download/agent-reach.zip e depois executa agent-reach setup. Todos os arquivos ficam reunidos em uma única pasta, ~/.agent-reach/, o que facilita bastante na hora de atualizar, gerenciar ou remover depois.
- Critério de aceitação: o Agent informa que a instalação foi concluída e, ao executar
agent-reach channels, o JSON retornado temokigual a true, com a lista de canais aparecendo emresult.
Passo 3: Pedir ao Agent para checar o status dos canais
Diga ao Agent “veja o status do Agent Reach”. Ele vai te contar quais canais estão funcionando agora e quais estavam de boa da última vez mas quebraram desde então. Esse passo funciona como um check-up, e recomendo rodá-lo também antes de investigar qualquer problema estranho mais adiante.
- Critério de aceitação: os cinco canais padrão — bilibili, v2ex, github, youtube e web — aparecem como disponíveis; já funcionalidades que dependem de condições extras, como as legendas do Bilibili e a transcrição de texto do YouTube, mostrarem “precisa de login” ou “precisa de Key” é perfeitamente normal.
Passo 4: adicionar canais opcionais e concluir o login
Tomando o Xiaohongshu como exemplo, diga ao Agent “adicione o Xiaohongshu para mim” e ele instalará automaticamente o software necessário. As plataformas que exigem login são tratadas pelo navegador dedicado que vem com o Agent-Reach, que roda em segundo plano, sem abrir janelas, e só fica acessível nesta máquina. Ele nunca faz login por você e jamais pede sua senha.
Algumas plataformas reaproveitam o estado de login que já existe no seu computador, copiando apenas o login desse site específico — o navegador original fica intacto e o cofre de senhas não é lido. Aqui é essencial ler o aviso de risco da próxima seção: se o que for reaproveitado for a conta principal, diga ao Agent “troque de conta” e use uma conta secundária.
- Critério de aceite: diga novamente “verifique o status do Agent Reach” e o xiaohongshu deve aparecer como disponível; em seguida, peça ao Agent para buscar uma palavra-chave e o resultado deve incluir o título e um trecho do corpo da nota.
Passo 5: executar a primeira tarefa de pesquisa multiplataforma
Basta descrever o objetivo em linguagem natural, por exemplo: “Use o Agent Reach para pesquisar o que as pessoas estão falando sobre determinado teclado mecânico, olhando notas do Xiaohongshu, legendas de vídeos de avaliação do Bilibili e discussões no Reddit, e no final resuma por plataforma.” O Agent vai decompor isso sozinho em vários comandos agent-reach <canal> <ação> [parâmetros] e executá-los.
- Critério de aceite: o resumo do Agent deve estar separado por plataforma, e cada opinião precisa apontar para a nota, vídeo ou post específico; se algum canal falhar, ele deve repassar a dica contida em
error.hintem vez de simplesmente ignorar em silêncio.
🚀 Dica para começar rápido: o Agent-Reach só se encarrega de trazer o conteúdo de volta — a compreensão e o resumo ficam por conta do Modelo de Linguagem Grande por trás do Agent. Se o seu Agent suporta interfaces de modelo personalizadas, você pode usar uma única chave API via APIYI apiyi.com para acessar modelos como Claude, GPT e Gemini. Novos usuários ganham cota gratuita de teste, ideal para validar a primeira tarefa de pesquisa com baixo custo.
Como configurar a interface de modelo APIYI no seu Agent
Se o seu Agent suporta interfaces compatíveis com OpenAI, a lógica de configuração é esta (os nomes exatos dos campos dependem da tela de configuração do Agent que você usa):
- Endereço da interface (base_url):
https://api.apiyi.com/v1 - Chave API: a chave criada no console APIYI
-
Nome do modelo: para pesquisas do dia a dia, recomendo
claude-sonnet-5-5; para tarefas leves em lote, pode usarclaude-haiku-5-5 -
Critério de aceitação: envie uma mensagem no Agent tipo “Olá, me diga qual modelo você é”. Se ele retornar conteúdo normalmente e o registro correspondente de invocação aparecer no console APIYI, está tudo certo.
Tabela de comandos mais usados do Agent-Reach
No uso diário, basta dizer ao Agent as frases da coluna da esquerda. Os comandos da direita servem para você entender o que o Agent faz por trás ou para investigar problemas no seu próprio terminal.
| O que você diz ao Agent | Comando executado pelo Agent | Finalidade |
|---|---|---|
| “Quais canais existem e o que cada um faz” | agent-reach channels |
Ver canais e capacidades |
| “Pesquise sobre Modelo de Linguagem Grande no Bilibili” | agent-reach bilibili search "大模型" |
Formato unificado: canal + ação + parâmetro |
| “Leia este link” | agent-reach read <link> |
Escolhe o canal automaticamente conforme o link |
| “Atualize o Agent Reach” | agent-reach update |
Atualiza de uma vez o programa, as ferramentas de cada canal e a skill |
| “Depois de instalar, diz que o comando não foi encontrado” | Rode uv tool update-shell e abra um novo shell |
Corrige o caminho do comando |
| (feito por você mesmo no terminal) | agent-reach configure groq-key |
Preenche a chave necessária para transcrição de voz em texto |
| “Desinstale o Agent Reach” | Lista primeiro o que será removido, apaga só depois da confirmação | Desinstalação segura |
Além disso, frases como “remova o Xiaohongshu”, “o login do Xiaohongshu expirou”, “saia da conta” e “deixe outro AI usar também” podem ser ditas diretamente ao Agent — você não precisa memorizar comando nenhum.
Aviso de risco do Agent-Reach (leia antes de usar)
⚠️ Leia esta seção com atenção antes de usar o Agent-Reach
- É uma ferramenta open source da comunidade, não uma API oficialmente autorizada de qualquer plataforma. Apenas recomendamos o projeto e não damos nenhuma garantia quanto à estabilidade, segurança ou conformidade dele.
- A conta pode ser limitada ou até banida. Plataformas como X, Xiaohongshu e Reddit podem considerar o acesso automatizado como comportamento anômalo. O próprio README oficial também recomenda explicitamente usar uma conta secundária — não rode o Agent com uma conta importante.
- Reaproveitar o login já existente na máquina pode acabar usando a conta principal. Alguns canais reaproveitam o estado de login que já está no computador, e a conta que você costuma usar é justamente a principal. Depois de ativar o canal, confirme primeiro qual conta está em uso e, se necessário, peça ao Agent para “trocar de conta” e usar a secundária.
- O risco é todo seu. Banimento, limitação de taxa, questões de conformidade na coleta e no uso dos dados — qualquer consequência desse tipo é de responsabilidade do leitor, e não da plataforma APIYI nem do autor deste artigo.
- Confira a origem da instalação. O pacote chamado agent-reach no PyPI não é este projeto; ele só pode ser instalado pelo endereço do GitHub. O projeto não tem nenhum token oficial, moeda, produto de investimento ou conexão com carteira — qualquer projeto cripto que use esse nome não tem relação com este repositório.
Tabela de solução de problemas do Agent-Reach
Os cinco problemas abaixo são os mais comuns na fase inicial — cada um tem um passo a passo que você pode seguir direto. Antes de começar a investigar, vale pedir ao Agent para executar um “ver o status do Agent Reach” e mostrar o texto original do error.hint.
| Sintoma | Causa | Solução |
|---|---|---|
Depois de instalar, aparece o aviso de que o comando agent-reach não foi encontrado |
O diretório de ferramentas do uv ainda não está no PATH | Peça ao Agent para executar uv tool update-shell e depois abra um novo shell (ou reinicie o Agent) e tente de novo |
| O Agent responde “não consigo executar comandos” | A permissão de execução de comandos não está ativada | Volte ao passo 1 e ative “Permitir execução de comandos” nas configurações do Agent |
| Vários erros após atualizar a partir da 1.5 | As versões 1.5 e anteriores foram instaladas via pipx/pip | Peça ao Agent para executar uv tool install --force junto com o endereço de instalação do GitHub, e depois rodar agent-reach setup — as chaves e configurações são mantidas |
| O Xiaohongshu de repente não retorna resultados na busca e pede login | A sessão de login expirou | Diga ao Agent “o login do Xiaohongshu expirou” e faça login novamente seguindo as instruções (recomendo usar uma conta secundária) |
| O canal X funciona de forma instável | O Twitter é um canal experimental e a plataforma tem anti-scraping mais rígido | Primeiro confira o status para ver se parou de funcionar; se estiver fora do ar, espere uma atualização do projeto e execute agent-reach update. Você também pode reportar no GitHub Issues |
Custos e escolha de modelos no Agent-Reach
O Agent-Reach em si é gratuito e não cobra taxa de API da plataforma. O que realmente gera custo é o token consumido quando o Agent que o executa invoca um Modelo de Linguagem Grande. A tabela abaixo mostra os preços de três modelos consultados no centro de documentação da APIYI apiyi.com em 26/10/2026, em dólares por milhão de tokens. Os modelos e preços devem ser conferidos na lista de modelos da plataforma.
| Modelo | Entrada | Saída | Leitura de cache | Tarefas ideais no Agent-Reach | Plataforma disponível |
|---|---|---|---|---|---|
| claude-opus-5-5 | $4 | $20 | $0.2 | Relatórios de pesquisa longos, validação cruzada de informações de várias fontes | APIYI apiyi.com |
| claude-sonnet-5-5 | $2 | $10 | $0.1 | Principal escolha para pesquisas multiplataforma do dia a dia | APIYI |
| claude-haiku-5-5 | $0.1 | $0.5 | $0.01 | Resumos em lote, buscas simples, verificação de status | APIYI |
Vamos fazer uma estimativa aproximada (não medida na prática): em uma pesquisa em 4 plataformas, o Agent lê 5 posts longos e mais 20 resultados de busca, com cerca de 30 mil a 60 mil tokens de entrada e 3 mil a 6 mil tokens de saída. Usando o claude-sonnet-5-5, cada execução fica em torno de US$ 0,10; com o claude-haiku-5-5, fica em menos de 1 centavo de dólar; e com o claude-opus-5-5, fica entre US$ 0,20 e US$ 0,35.
A recomendação é bem direta: comece rodando o fluxo com o sonnet e depois decida se vale a pena subir para o opus conforme a qualidade dos resultados. Tarefas repetitivas em lote ficam com o haiku. O Agent-Reach devolve conteúdo estruturado e organizado, o que por si só economiza tokens em comparação a fazer o Agent ler páginas web brutas. Se for usar por muito tempo, também vale ficar de olho na economia proporcionada pelo preço de leitura de cache.
Perguntas frequentes (FAQ)
P1: O Agent-Reach é realmente totalmente gratuito?
O Agent-Reach em si é gratuito e tem código aberto sob licença MIT, e as plataformas também não cobram taxa de API. O único custo que você paga é o dos tokens usados quando o Agent chama o Modelo de Linguagem Grande. Pela estimativa acima, uma pesquisa envolvendo 4 plataformas com um modelo de nível sonnet custa cerca de US$ 0,1. Se quiser testar primeiro, você pode resgatar a cota gratuita de teste para novos usuários no APIYI apiyi.com e rodar sua primeira tarefa.
P2: O Agent vai usar minha conta para postar, curtir ou mandar mensagens diretas?
Não. O Agent-Reach é uma ferramenta somente leitura: ele apenas pesquisa e lê, não publica, não comenta, não curte e não envia mensagens diretas. Mas somente leitura não significa risco zero: as plataformas ainda podem interpretar leituras em alta frequência como acesso anômalo, então continua valendo a recomendação de usar uma conta secundária. Veja a seção de avisos de risco para mais detalhes.
P3: Como ativar a transcrição de voz do YouTube e do Xiaoyuzhou? Preciso enviar a chave para o Agent?
A transcrição do YouTube precisa de uma chave Groq ou OpenAI, e o Xiaoyuzhou precisa de uma chave Groq. **Não envie a chave diretamente no chat**. O procedimento oficial exige que você execute `agent-reach configure groq-key` no seu próprio terminal para preencher. Para validar: peça ao Agent para transcrever um vídeo do YouTube; o JSON retornado deve ter `ok` como true e conter o texto.
P4: Qual modelo funciona melhor com o Agent-Reach?
Para pesquisas do dia a dia, recomendo começar com o claude-sonnet-5-5, que equilibra bem a compreensão de conteúdo de múltiplas fontes e o controle de custos; quando precisar de análise mais profunda, mude para o claude-opus-5-5. Com uma única chave no APIYI apiyi.com, você consegue alternar entre esses modelos mudando apenas o nome do modelo, sem alterar o endereço da interface. Isso facilita comparar os resultados usando a mesma tarefa de pesquisa.
P5: Já instalei no Claude Code; como faço outro Agent também usar?
Basta dizer ao Agent já configurado: “faça outro AI também conseguir usar”. Ele vai cuidar da configuração compartilhada. Como todos os arquivos ficam centralizados na pasta `~/.agent-reach/`, o outro Agent só precisa ter a permissão de executar comandos habilitada para chamar. Para validar: no novo Agent, diga “veja o status do Agent Reach” e ele deve retornar a mesma lista de canais do Agent original.
Pontos-chave do tutorial do Agent-Reach
- Definição em uma frase: O Agent-Reach permite que o Agent leia conteúdos por trás de muros de login, dentro de vídeos e em plataformas chinesas.
- Instalação: basta enviar o link oficial do install.md para o Agent — ele mesmo instala o uv e o agent-reach.
- Três níveis de canais: 5 canais padrão prontos para uso, 6 opcionais que se ativam com uma frase e 3 experimentais que podem parar de funcionar a qualquer momento.
- Design somente leitura: não publica posts, não curte, não envia mensagens diretas; a saída é sempre um JSON com o campo
ok. - Segurança da conta: as ferramentas da comunidade não são APIs oficiais e podem acionar limite de requisições ou banimento — use sempre uma conta secundária.
- Custo controlado: a taxa de API da plataforma é zero; o custo principal vem dos tokens do modelo, que podem ser cobrados por uso via APIYI apiyi.com.
Resumo
Os pontos centrais do tutorial do Agent-Reach:
- Resolve uma dor real: notas do Xiaohongshu, atualizações de contas do X, legendas do Bilibili — coisas que a busca genérica não encontra. Agora o Agent consegue ler tudo isso diretamente.
- Sem barreira de entrada: basta uma frase para o Agent concluir a instalação. Depois, adicionar canais, trocar de conta e atualizar — tudo em linguagem natural.
- Riscos que você precisa conhecer: é uma ferramenta open source da comunidade. Use uma conta secundária, confira bem quais contas estão sendo reutilizadas e assuma o julgamento e a responsabilidade pelas consequências.
A sugestão é começar rodando uma pesquisa no Bilibili ou no GitHub com os canais padrão, confirmar que cada etapa de validação passou e só então adicionar, conforme a necessidade, os canais que exigem login, como Xiaohongshu e Reddit.
Se precisar de modelo, pode usar o APIYI apiyi.com.
📚 Referências
- Repositório GitHub do Agent-Reach: código-fonte do projeto, README e descrição dos canais
- Link:
github.com/Panniantong/Agent-Reach -
Descrição: é a única fonte de instalação confiável; a lista de canais e as instruções de segurança devem ser consultadas por aqui
-
Instruções oficiais de instalação do Agent-Reach: documentação de instalação feita para o Agent ler
- Link:
raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/install.md -
Descrição: é justamente esse o endereço enviado ao Agent no passo 2 deste artigo
-
GitHub Issues do Agent-Reach: canal para reportar problemas
- Link:
github.com/Panniantong/Agent-Reach/issues - Descrição: quando um canal experimental falhar ou der erro na instalação, você pode pesquisar ou reportar por aqui
Autor: Equipe técnica da APIYI
Contato técnico: fique à vontade para falar com a gente pela página inicial do site da APIYI; mais materiais estão disponíveis no centro de documentação docs.apiyi.com
