Redes sociais com agentes de IA · Capítulo 5 de 9 · 9 min
Dê ao agente a documentação de hoje para ele não inventar a integração
Como fazer o agente consultar a documentação atual de cada ferramenta antes de escrever código de integração, e onde essa consulta deixa de valer.
Este capítulo faz parte do curso gratuito Redes sociais com agentes de IA.
Na terça seguinte ao primeiro post aprovado, Rafael pediu ao agente um script para agendar o carrossel da semana do @estudioventana pela Publora. O código veio limpo, comentado e errado em dois pontos: mandava a chave num cabeçalho de autorização que a API não lê e agendava o post antes de terminar o envio das imagens. Rafael só percebeu porque manteve o teste de agendar e apagar definido no capítulo anterior.
O prejuízo de deixar passar seria maior que a tarde perdida. Na Publora, agendar antes de o upload terminar faz a rede publicar sem mídia ou recusar o post, e o Instagram não aceita post sem mídia. O Ventana, que neste curso é um exemplo didático, já tinha tido um número inventado no ar; um carrossel vazio com a marca da consultoria seria o segundo incidente público em poucos meses.
O agente não mentiu. Ele escreveu a integração com o que aprendeu no treinamento, e APIs de publicação mudam nome de campo, limite e fluxo mais depressa do que modelos são treinados de novo. Este capítulo mostra como colocar a documentação de hoje dentro da conversa, para que o agente consulte antes de escrever, e onde essa consulta para de valer.
Documentação viva: o agente consulta antes de escrever
Documentação viva é a prática de entregar ao agente, no momento da tarefa, o trecho atual da documentação oficial da ferramenta que ele vai integrar. A memória do modelo continua útil para a lógica do código. Os detalhes que mudam, como nome de cabeçalho, ordem obrigatória de chamadas e limites por plano, passam a vir de uma fonte consultada naquela hora.
O Context7, projeto da Upstash, é o exemplo mais citado em outubro de 2026. Ele indexa a documentação de bibliotecas e APIs e a entrega a agentes como Claude, Codex e Cursor. A instalação sugerida pelo projeto é npx ctx7 setup, que configura o servidor MCP no agente.
Com ele ligado, o agente ganha duas ferramentas. A primeira, resolve-library-id, recebe um nome como "publora" e devolve o identificador da biblioteca indexada. A segunda, query-docs, recebe esse identificador e um tópico e devolve os trechos da documentação que tratam dele. A ordem importa: quem pula o primeiro passo costuma consultar a biblioteca errada, porque nomes parecidos convivem no índice, e a Apify, por exemplo, aparece com mais de uma entrada.
Se a figura ultrapassar a área visível, deslize para os lados. Pelo teclado, foque a figura e use as setas.
Bibliotecas indexadas no Context7 que a operação do Ventana usa (consulta em 22/10/2026)
| Ferramenta | Identificador no Context7 | Trechos indexados | O que perguntar |
|---|---|---|---|
| Publora | /publora/publora-api-docs | 2.838 | Fluxo de rascunho, upload e agendamento; cabeçalho de autenticação; limites por rede |
| Apify | /apify/apify-docs | 6.402 | Teto de cobrança por execução, cobrança por evento, filtro de atores no servidor MCP |
| Apify, API v2 | /websites/apify_api_v2 | Não informado | Parâmetros exatos de chamada de um ator pela API REST |
| instagram-skills | /sergebulaev/instagram-skills | 497 | O que cada skill pede de entrada e devolve de saída |
A Publora declara que mantém a documentação indexada no Context7 para que assistentes de código já conheçam a API. A contagem de trechos muda a cada reindexação; confira no momento do uso.
Exemplo resolvido: o carrossel do Ventana com a fonte certa
Rafael descartou o script e refez o pedido com uma instrução a mais: consultar a documentação da Publora antes de escrever qualquer linha. O agente chamou resolve-library-id com o nome da ferramenta, recebeu /publora/publora-api-docs e chamou query-docs com o tópico do carrossel no Instagram. A resposta trouxe três fatos que corrigiam o primeiro script.
A autenticação usa o cabeçalho x-publora-key, e a chave aparece uma única vez na criação, por isso precisa estar guardada fora do código. O fluxo do Instagram tem três tempos obrigatórios: um rascunho criado sem horário, cada mídia enviada por URL pré-assinada e só então o agendamento. O horário vai em UTC, no formato ISO 8601, com pelo menos cinco minutos de antecedência.
Agente recebe a tarefa de integração | v resolve-library-id com o nome da ferramenta | v query-docs com o tópico exato da tarefa | v Script escrito citando o trecho que sustenta cada chamada | v Teste reversível: agendar para daqui a uma hora e apagar | v Portão de aprovação humana do post real
Com o script novo, Rafael repetiu o teste reversível e só depois Marina aprovou o post real. A tarde perdida virou regra escrita no arquivo de instruções do projeto: integração nova começa por consulta à documentação, e o agente cita o trecho que usou.
Como consultar a documentação da Publora pelo Context7 antes de pedir uma integração
Guia de referência para Claude Code, Codex ou Cursor. O mesmo caminho vale para a Apify e para a instagram-skills, trocando o nome da biblioteca.
Passo 1: Instale o servidor do Context7
No terminal do projeto, rode `npx ctx7 setup` e siga as perguntas para ligar o MCP do Context7 ao seu agente.
Deu certo quando: O agente mostra resolve-library-id e query-docs entre as ferramentas disponíveis.
Passo 2: Resolva o identificador
Peça ao agente que chame resolve-library-id com o nome "publora" e mostre qual resultado escolheu.
Deu certo quando: O identificador /publora/publora-api-docs aparece na resposta, com o motivo da escolha.
Passo 3: Consulte o tópico exato da tarefa
Peça query-docs com um tópico fechado, por exemplo "carrossel no Instagram, upload de mídia e agendamento".
Deu certo quando: A resposta traz o fluxo de rascunho sem horário, upload por URL pré-assinada e agendamento.
Passo 4: Extraia os fatos que mudam o código
Peça a lista com cabeçalho de autenticação (x-publora-key), ordem das chamadas, formato do horário (UTC, ISO 8601) e antecedência mínima de cinco minutos.
Deu certo quando: Cada fato vem acompanhado do trecho de origem.
Passo 5: Só então peça o script
Use o prompt de integração com consulta obrigatória e exija um comentário citando o trecho que sustenta cada chamada.
Deu certo quando: Nenhuma chamada do script fica sem origem declarada.
Passo 6: Limpe o que vai na consulta
Antes de colar uma mensagem de erro para diagnóstico, apague chave, senha e qualquer dado de cliente.
Deu certo quando: Nada sensível saiu da sua máquina.
No fim você tem: Um script de integração em que cada chamada aponta para a documentação consultada naquele dia.
O que a consulta deixa de fora
A documentação viva reduz o erro de integração e deixa três coisas fora do alcance dela. O painel da ferramenta é a primeira: na Publora, as contas sociais se conectam por OAuth na área de canais, e nenhuma chamada de API faz essa ligação. Agente que promete conectar o Instagram por código está inventando, mesmo depois de consultar.
O teste real é a segunda. Um trecho indexado pode estar defasado em relação à versão publicada, e só a execução mostra o comportamento de hoje. Por isso o teste de agendar e apagar continua obrigatório em toda integração nova, com ou sem Context7. A terceira é o critério editorial, porque a documentação diz como publicar e cala sobre se aquele post deve ir ao ar.
Como fazer o teste reversível de agendar e apagar depois de uma integração nova
Guia de referência para conferir, sem publicar nada, que a integração funciona com a API de hoje.
Passo 1: Confira o canal no painel
No painel da Publora, abra a área de canais (Channels) e confirme que a conta do Instagram está conectada por OAuth.
Deu certo quando: A conta aparece como conectada; nenhuma ligação foi tentada por código.
Passo 2: Crie o rascunho sem horário
Rode a primeira etapa do script, que cria o post sem data de publicação.
Deu certo quando: O rascunho aparece no painel, ainda sem agendamento.
Passo 3: Suba cada mídia antes de agendar
Envie cada imagem pela URL pré-assinada e espere a confirmação de todos os uploads.
Deu certo quando: Todas as imagens constam como anexadas ao rascunho.
Passo 4: Agende com folga
Agende em UTC, no formato ISO 8601, para uma hora à frente, bem acima do mínimo de cinco minutos.
Deu certo quando: O post aparece como agendado, com as imagens.
Passo 5: Confira e apague
Abra o post agendado no painel, confira mídia, legenda e horário e exclua o agendamento antes da hora.
Deu certo quando: O post sai da fila e nada vai ao ar.
Passo 6: Registre o resultado
Anote data, resultado e versão do script no arquivo de instruções do projeto.
Deu certo quando: Quem mexer na integração depois sabe quando ela passou no teste.
No fim você tem: Prova datada de que a integração funciona, sem nenhum post publicado por engano.
O próprio Context7 pede que a consulta não leve chave, senha, dado pessoal nem código proprietário. O deslize típico acontece no diagnóstico: alguém cola no chat a mensagem de falha inteira da API, com o cabeçalho e a chave junto, e pede ao agente que pesquise a causa. Apague a chave e qualquer dado de cliente antes de colar. Se a chave já passou por uma conversa, gere outra no painel e revogue a antiga no mesmo dia.
Erros comuns com documentação viva
| Sintoma | Causa provável | Saída |
|---|---|---|
| O agente usa um parâmetro que a API recusa | Escreveu de memória, sem consultar | Exigir no pedido a citação do trecho consultado para cada chamada |
| A consulta devolve documentação de outra ferramenta | Pulou resolve-library-id ou aceitou o primeiro resultado sem conferir | Pedir que o agente mostre o identificador escolhido antes de consultar |
| O script passa no teste e falha semanas depois | A API mudou depois da indexação ou depois do teste | Repetir o teste reversível sempre que a integração mudar ou falhar |
Na segunda-feira, abra o arquivo de instruções do seu projeto e escreva a regra que o Ventana adotou: toda integração começa por resolve-library-id e query-docs, o agente cita o trecho usado e nenhum script chega à produção sem o teste de agendar e apagar. O critério de pronto se confere em um minuto, porque o próximo script entregue traz, em comentário, a origem de cada chamada. Rafael ganhou isso na primeira semana, e foi o que liberou tempo para o assunto seguinte, o próprio Instagram.
Seu caderno neste capítulo
Abrir o caderno completoSelecione um trecho do capítulo para destacar ou anotar. Nos vídeos e áudios, use Anotar este momento. No teclado, selecione com Shift e as setas e use Alt+Shift+D para destacar ou Alt+Shift+N para anotar.
Salvo neste navegador. Entre na sua conta para levar o caderno a outros aparelhos.
Entre na sua conta para compartilhar o que aprendeu e convidar alguém para estudar com você.
Conexões deste capítulo
Veja o que estudar antes e para onde seguir depois, explore os conceitos e compare abordagens em outros cursos. Sugestões marcadas como “sugerido pelo grafo” vêm dos assuntos em comum, não do índice do curso.
Estude antes
- Configurar o Codex com GPT-6 Astra num sandbox que pede aprovaçãosugerido pelo grafoApresenta o conceito “Codex”, usado em “Dê ao agente a documentação de hoje para ele não inventar a integração”.
- CursoSkills de IA com Vibecoding e Terminalsugerido pelo grafoAs skills de redes sociais são instaladas e acionadas no terminal: quem já usa skills no Claude Code monta a operação sem tropeçar na instalação.
O mesmo assunto em outros cursos
- Agentes de IA Autônomos: Do Conceito à ProduçãoClaude Agent SDKExaminar conexões de Claude Agent SDK
- Frontends com VibecodingConfigurar ambiente, skills e o contêiner de contextoExaminar conexões de Configurar ambiente, skills e o contêiner de contexto
- Bastidores: Como Este Portal Foi ConstruídoO que foi entregue: o portal em telasExaminar conexões de O que foi entregue: o portal em telas
- Segundo cérebro com IAComo ligar o assistente à agenda de reservas sem perder o controleExaminar conexões de Como ligar o assistente à agenda de reservas sem perder o controle
Terminou a leitura?
Marque como concluído para o capítulo contar no seu painel e no certificado.
Leve uma ideia para a prática
Escolha uma atividade no painel e volte a este curso quando quiser.
Atividades e evolução ficam reunidas no painel da sua conta.