Isenção de responsabilidade: Este guia cobre o acesso a dados disponíveis publicamente. Sempre revise o robots.txt e os Termos de Serviço de um site antes do acesso automatizado.

Agentes precisam de dados ao vivo. Um pipeline RAG ou assistente de desenvolvedor autônomo é tão útil quanto a janela de contexto que você fornece. Ao trabalhar com ferramentas de desenvolvedor, isso geralmente significa dar ao seu agente de IA acesso aos dados do GitHub.

A busca de HTML bruto quebra rapidamente contra a limitação de taxa moderna. Este guia mostra como conectar seu LLM de forma segura a repositórios públicos do GitHub, extrair JSON estruturado e manter suas chamadas de ferramenta confiáveis.

Por que agentes de IA precisam de dados do GitHub

Fornecer LLMs com contexto do GitHub em tempo real desbloqueia várias capacidades autônomas que bases de conhecimento estáticas simplesmente não podem suportar. Quando um agente está intimamente integrado com dados de repositórios públicos, as aplicações potenciais escalam dramaticamente.

• Monitoramento de repositórios: Agentes podem rastrear a velocidade de problemas, tempos de revisão de PR e a responsividade dos mantenedores em repositórios-alvo. Isso permite que equipes de engenharia meçam automaticamente a saúde de suas dependências de código aberto.
• Rastreamento de tendências tecnológicas: Pipelines podem analisar repositórios em alta, extraindo linguagens usadas, estrelas e padrões arquitetônicos para alimentar ferramentas de pesquisa de mercado. Ao analisar arquivos README.md e descrições de repositórios, um agente pode classificar tecnologias emergentes.
• Escaneamento de dependências: Scanners de segurança autônomos podem ler arquivos de manifesto públicos (como package.json ou requirements.txt) diretamente de branches para construir relatórios de vulnerabilidade. Isso é crítico para agentes encarregados de manter a segurança da cadeia de suprimentos.

Por que requisições HTTP brutas falham para agentes

Quando um agente executa uma chamada de ferramenta usando um requests.get() padrão ou curl, geralmente falha. O GitHub, como a maioria das grandes plataformas, emprega limitação de taxa rigorosa e detecção de bots.

Agentes operam em um loop de "Pensar, Agir, Observar". Se uma requisição HTTP retorna um 403 Proibido ou um desafio CAPTCHA durante a fase de "Agir", o LLM ingere essa página de erro em sua janela de contexto durante a fase de "Observar". Isso contamina o contexto. Desperdiça o orçamento de tokens e geralmente faz com que o agente alucine uma resposta ou entre em um loop tentando corrigir a requisição.

Além disso, mesmo que a requisição tenha sucesso, bibliotecas HTTP padrão retornam HTML bruto. Despejar 500KB de HTML bruto do GitHub em um prompt destrói a relação sinal-ruído. O agente tem que analisar estruturas DOM complexas, classes CSS e scripts inline. Isso não apenas aumenta seus custos de API ao esgotar a janela de contexto, mas degrada fundamentalmente o desempenho de raciocínio do LLM em sua tarefa real. O modelo gasta seu mecanismo de atenção analisando árvores DOM em vez de analisar os dados.

Conectando seu agente ao GitHub via AlterLab

Para corrigir essa falha arquitetônica, substituímos chamadas HTTP brutas por uma API de dados robusta. Nosso endpoint de extração lida com a renderização do navegador, rotação de proxy e analisa a página alvo diretamente em dados estruturados. Antes de começar, certifique-se de conferir nosso guia de introdução.

Usando a documentação da API de Extração como referência, você pode definir estritamente o esquema que seu agente espera. Isso garante que o LLM receba a estrutura JSON exata necessária para seu próximo passo de raciocínio, contornando completamente a necessidade do modelo de analisar HTML.

```python title="agent_github-com.py" {3-7}

client = alterlab.Client("SUA_CHAVE_API")

Extração estruturada — obtenha dados limpos sem analisar HTML

result = client.extract(
url="https://github.com/example-page",
schema={"title": "string", "price": "string", "description": "string"}
)
print(result.data) # Dicionário estruturado limpo, pronto para seu LLM

```bash title="Terminal" {3-5}
curl -X POST https://api.alterlab.io/api/v1/extract \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/kubernetes/kubernetes", 
    "schema": {
      "repository_name": "string", 
      "stars": "number",
      "about_description": "string"
    }
  }'

A resposta é um dicionário limpo e determinístico. O LLM gasta zero tokens analisando tags. Você pode passar isso diretamente para uma interface de chamada de função ou simplesmente anexá-lo como uma mensagem de sistema.

Usando a API de Pesquisa para consultas do GitHub

Frequentemente, um agente não sabe a URL exata do repositório de antemão. Ele precisa descobrir repositórios com base em uma consulta em linguagem natural ou um código de erro que acabou de encontrar. A API de Pesquisa permite que seu agente execute buscas programáticas e receba uma lista estruturada de resultados, imitando fluxos de trabalho de descoberta humana.

```python title="github_search_tool.py" {5-9}

def search_github(query: str, api_key: str):
response = requests.post(
"https://api.alterlab.io/api/v1/search",
headers={"X-API-Key": api_key},
json={
"query": f"site:github.com {query}",
"num_results": 5
}
)
return response.json()

Quando envolvido como uma ferramenta MCP, o agente pode pesquisar ativamente por "exemplos de middleware fastapi", analisar o array JSON limpo de resultados de pesquisa e, em seguida, iterar através das URLs extraídas usando a API de Extração. Isso cria um pipeline de pesquisa autônomo em várias etapas que nunca é bloqueado por limites de taxa.

## Integração MCP

Construir wrappers de ferramentas personalizados para cada endpoint de API e gerenciar a validação de esquema é tedioso. Se você estiver construindo com Claude, Cursor ou qualquer framework que suporte o Protocolo de Contexto do Modelo, pode conectar nosso serviço diretamente como um servidor pré-configurado.

Isso expõe as capacidades de extração e pesquisa nativamente ao agente. O agente entende automaticamente os requisitos de esquema, as entradas esperadas e pode formatar suas próprias chamadas de ferramenta sem engenharia de prompt manual. Para detalhes completos de configuração, leia a documentação sobre [AlterLab para Agentes de IA](https://alterlab.io/docs/tutorials/ai-agent).

<div data-infographic="steps">
  <div data-step data-number="1" data-title="Agente solicita dados" data-description="Agente LLM chama ferramenta MCP com URL alvo"></div>
  <div data-step data-number="2" data-title="Plataforma busca + extrai" data-description="Lida com anti-bot, retorna JSON estruturado"></div>
  <div data-step data-number="3" data-title="Agente usa dados limpos" data-description="Sem análise, sem tentativas — os dados vão direto para o contexto do LLM"></div>
</div>

## Construindo um pipeline de monitoramento de repositórios

Vamos construir um pipeline RAG de ponta a ponta. O objetivo: dar a um agente uma lista de repositórios alvo, fazer com que ele extraia o histórico de commits mais recente e problemas abertos, e sintetizar um relatório de status diário. Definimos um esquema preciso para que o agente receba apenas os campos exatos de que precisa.


```python title="repo_monitor_pipeline.py" {11-17}

from openai import OpenAI

def fetch_issues_page(repo_url: str) -> dict:
    api_key = os.getenv("API_KEY")
    issues_url = f"{repo_url}/issues"

    payload = {
        "url": issues_url,
        "schema": {
            "open_issues_count": "number",
            "top_issues": [{
                "title": "string",
                "opened_by": "string",
                "time_opened": "string"