O que o agente lê

O agente não tem acesso à sua infraestrutura: ele tem acesso a um conjunto de ferramentas de leitura, e cada uma delas é uma pergunta específica que o RootPilot Agent sabe executar dentro da sua infra.

São mais de duas centenas hoje, e o número muda a cada release — por isso esta página não as lista. Uma lista colada à mão envelheceria no primeiro deploy e passaria a mentir para você. O que ela faz é explicar como a superfície é decidida, e como descobrir a sua.

A superfície não é fixa — ela depende da sua frota

É o conceito central, e o mais fácil de errar. Duas organizações com o mesmo RootPilot veem conjuntos diferentes de ferramentas.

O motivo é simples: uma ferramenta que precisa da sua infra só é anunciada se alguma operação de catálogo que ela executa está sendo servida por um Agent conectado agora. Sem connector de Kubernetes configurado, as leituras de pod não existem para o modelo. Com Grafana no lugar de Datadog, as leituras de métrica continuam existindo — porque a operação é a mesma; muda quem a atende.

A exceção fica do nosso lado: uma ferramenta que responde a partir do que já foi aprendido sobre o seu ambiente (topologia registrada, notas, o grafo de recursos, a própria saúde da frota) não pergunta nada à sua infra, então nunca é escondida — ela continua respondendo com a frota inteira fora do ar.

Isso muda a sua pergunta de “o produto tem X?” para “a minha frota serve X?”.

O gate é conservador de propósito, e vale saber como:

Ele esconde só com conhecimento positivo. Se não sabemos o que a frota serve (frota vazia, Agent de versão antiga que não reporta connector nenhum), a superfície aparece inteira em vez de sumir.
Ele acompanha a saúde, não só a presença. Um connector cujo credencial parou de funcionar sai do conjunto servido, e as ferramentas que dependiam só dele desaparecem — o mesmo evento que a saúde de frota reporta.
Uma análise composta que cruza vários sinais aparece se algum deles é servido, e degrada dizendo o que faltou. Escondê-la inteira seria pior do que entregá-la parcial e honesta. A exceção é a operação de entrada, sem a qual a análise não começa: aí ela some, em vez de ser anunciada para falhar depois.
O conjunto é decidido quando a sessão abre. Um connector que volta no meio de uma investigação aparece na sessão seguinte, não naquela.

Se uma ferramenta escondida for chamada assim mesmo, a recusa é imediata e nomeia as operações que ninguém serve — em vez de mandar o agente tentar conectar num lugar onde não há credencial.

Como descobrir o que a sua frota serve

Três superfícies, e elas respondem perguntas diferentes:

Onde	O que responde
`tools/list`, do seu próprio cliente	O que esta sessão pode chamar. É a resposta autoritativa, já filtrada pela sua frota.
A ferramenta `check_fleet_health`	Por que algo está faltando: connector por connector, o estado agora.
A página Catálogo, no control-plane	O que o produto tem, independentemente da sua frota. Bom para saber o que existiria se você conectasse a fonte.

O check_fleet_health é a que vale aprender a ler, e ela está entre as ferramentas anunciadas desde o início da sessão justamente para ser um preflight. O vocabulário dela:

Estado	Significa
`up`	Servido e saudável
`degraded`	Servido, com parte falhando ou cobertura incompleta
`down`	Servido, e todos os servidores em erro — tipicamente credencial
`unchecked`	Servido, mas sem sondagem de credencial — este connector não expõe uma
`not_configured`	O Agent conhece a integração e não tem credencial para ela (secret ausente)

Duas leituras que economizam uma investigação errada: unchecked não é “sondagem atrasada”, é connector que não traz sonda nenhuma — esperar não muda o valor; e a frescura é do rollup inteiro (checked_age_seconds, no topo da resposta), não de cada connector.

Além dos connectors, ela devolve um veredito da frota inteira. Frota sem nenhum Agent conectado não se parece com frota saudável: ela diz isso em campo próprio, porque três listas vazias teriam exatamente a mesma cara de “tudo certo, nada degradado”.

`search_tools`: anunciar tudo ou descobrir sob demanda

Anunciar duas centenas de ferramentas ocupa uma fatia grande do contexto do modelo antes de ele fazer qualquer coisa. Existe um modo alternativo, desligado por padrão:

Desligado (default). O tools/list anuncia toda a superfície servida pela sua frota. Simples, compatível com qualquer cliente.
Ligado. O tools/list anuncia só um núcleo curado mais a meta-ferramenta search_tools. O agente busca pelo que precisa, os resultados passam a valer naquela sessão, e o servidor emite tools/list_changed para o cliente re-buscar a lista.

O trade-off é esse: o modo ligado economiza contexto e custa um passo de descoberta — e pede um cliente que entenda tools/list_changed. Um cliente que ignore a notificação não verá as ferramentas descobertas no tools/list (o próprio resultado da busca as nomeia, então o modelo ainda consegue chamá-las). É por isso que o default é o modo simples.

A busca respeita o mesmo gate: ela não oferece como “disponível agora” uma ferramenta que a sua frota não consegue executar.

Leituras atômicas e análises compostas

A superfície tem dois tipos de ferramenta, e a diferença é de altitude:

Leituras atômicas respondem uma pergunta contra uma fonte: as métricas de um serviço, os logs de uma janela, os security groups de uma conta.
Análises compostas respondem uma pergunta de investigação, cruzando muitas leituras: investigue este incidente, como está a produção, qual o raio de impacto se este recurso cair.

O que você ganha pedindo a composta em vez de costurar as atômicas à mão não é só conveniência. É a correlação entre as fontes (o deploy que coincide com a queda, o vizinho de topologia que explica a latência) e, principalmente, a contabilidade de cobertura: a composta sabe quantas fontes deveriam ter respondido e reporta as que não responderam. Dezenove leituras soltas não somam essa propriedade sozinhas.

A sessão nasce com contexto

Além das ferramentas, o servidor entrega ao modelo, na abertura da sessão, um contexto curto e derivado do que já foi aprendido sobre o seu ambiente: topologia observada, particularidades já registradas, e — quando existe — a política da sua organização e qual backend de observabilidade de fato atende a sua frota.

O último item parece detalhe e não é: sem saber que quem responde é o SigNoz e não o Datadog, o modelo escreve consultas no dialeto errado e recebe erro. Dizer isso na abertura é mais barato do que deixá-lo descobrir por tentativa.

As respostas dizem o que não conseguiram ver

Esta é a característica mais distintiva do produto, e provavelmente a menos óbvia na primeira leitura.

Toda resposta carrega um campo _sources: de quais fontes ela veio, e em que estado cada uma respondeu. O vocabulário é fechado, e cada palavra declara em qual das quatro classes aquilo cai: leitura, escolha de não perguntar, impossibilidade de perguntar ou cegueira. A partir daí, o formato da resposta muda:

Fonte cega — o corpo é descartado. Se todas as fontes que deveriam responder falharam, a resposta não volta com zeros: volta como envelope, com visibility: "none", error: "no_visibility" e um aviso nomeando as fontes. Some inclusive a prosa, que é justamente a parte que mentiria. O que sobrevive é o diagnóstico e os argumentos com que a leitura foi feita — porque descartar o corpo não pode custar saber sobre o quê ficamos cegos.
Cobertura parcial — o corpo fica, anotado. Havendo dado real, ele volta, com visibility: "partial" e a contabilidade do que faltou.
Vazio nunca vira zero. Uma contagem que veio de uma operação que não respondeu é null ou some — não 0.
Ausência exige prova. Afirmar que algo não existe requer uma leitura que tenha de fato acontecido. Sem ela, o resultado é inconclusivo, e diz isso.

As duas primeiras regras são estruturais: valem num ponto único, por onde toda resposta passa. As duas últimas são a disciplina que cada ferramenta segue dentro do próprio corpo — é a diferença entre uma garantia do formato e uma regra de conteúdo, e vale conhecê-la para saber o que checar quando um número parecer bom demais.

O mesmo raciocínio governa os vereditos: uma nota, uma classificação, um “está tudo bem”. Onde a nota sai de penalidade, uma leitura que falha melhoraria o número — então a nota não é emitida quando a fonte ficou cega, e o que foi observado volta marcado como parcial. Cegueira total descarta o veredito junto com o corpo; sob cobertura parcial, quem segura a conclusão é cada ferramenta.

A leitura tem escopo, e ele é dito

Em nuvem, toda leitura acontece dentro de uma conta (ou projeto, ou tenant). Qual delas foi lida viaja de volta na resposta em qualquer nuvem, e isso não é enfeite: um Agent apontado para o lugar onde quase não há nada é indistinguível de uma conta vazia, se ninguém disser onde ele olhou. Na AWS volta também a região, pela mesma razão.

Quando há mais de uma conta roteável, a ferramenta pede que você escolha, ou aceita varrer todas de uma vez ("all"). Duas ressalvas que valem antes de confiar numa varredura:

Na AWS, ela declara o que não varreu — contas conhecidas fora do alcance da frota aparecem nomeadas e a visibilidade cai para parcial. Quatro de quinze contas nunca é uma resposta completa. Em GCP e Magalu essa contabilidade ainda não existe: a varredura cobre o que a frota serve, sem enumerar o que ficou fora.
A varredura para em 12 contas. As demais voltam listadas como ignoradas, com o motivo — não somem.

Tirar leitura da superfície

Nem toda leitura precisa ser concedida. A denylist de tools é como você diz “pode ler minhas métricas e meus logs, mas não os meus security groups” — composta por você, aplicada pelo Agent dentro da sua infra.

O que acontece com a superfície quando você nega algo:

As ferramentas que dependiam só das operações negadas somem — do anúncio e da execução.
As que dependiam em parte continuam, degradando, e a resposta carrega a anotação de que a política removeu uma parte do que ela veria.
A supressão é legível: a fonte negada é reportada como denied_by_policy, que conta como não consegui ler e nunca como não existe. “A política me proibiu” não é prova de ausência — e essa distinção é o motivo de a denylist não ser uma subtração silenciosa.

A sessão também sabe da política antes de precisar dela, então a resposta a uma pergunta em área negada é “isso está desabilitado pela política da sua organização”, e não “não encontrei nada”. O que ela conhece é a política que o Agent anunciou de volta — uma que você compôs e ainda não implantou não aparece ali, e é por isso que a Frota mostra rascunho e aplicado lado a lado.

O que esta página não cobre

A lista das ferramentas. Por decisão: ela é descoberta, não documentada — ver como descobrir.
A escrita. As quatro exceções e os gates que as cobrem estão em o que o agente escreve.
O que é redigido antes de sair da sua infra — Redação de PII.