Lo que lee el agente

El agente no tiene acceso a tu infraestructura: tiene acceso a un conjunto de tools de lectura, y cada una es una pregunta específica que el WhyStack Agent sabe ejecutar dentro de tu infra.

Hoy son unos cuantos cientos, y el número cambia con cada release, por eso esta página no las lista. Una lista pegada a mano quedaría obsoleta en el primer deploy y empezaría a mentirte. Lo que hace esta página es explicar cómo se decide la superficie, y cómo descubrir la tuya.

La superficie no es fija: depende de tu flota

Este es el concepto central, y el más fácil de entender mal. Dos organizaciones que corren el mismo WhyStack ven conjuntos distintos de tools.

La razón es simple: una tool que necesita tu infra solo se anuncia si alguna operación del catálogo que ejecuta está siendo servida por un Agent conectado en este momento. Sin un connector de Kubernetes configurado, las lecturas de pods no existen para el modelo. Con Grafana en lugar de Datadog, las lecturas de métricas siguen existiendo, porque la operación es la misma; lo que cambia es quién la responde.

La excepción está de nuestro lado: una tool que responde a partir de lo que ya se aprendió sobre tu entorno (la topología registrada, las notas, el grafo de recursos, la propia salud de la flota) no le pregunta nada a tu infra, así que nunca se oculta: sigue respondiendo con toda la flota fuera de línea.

Eso convierte tu pregunta de “¿el producto tiene X?” en “¿mi flota sirve X?”.

El gate es conservador a propósito, y vale la pena saber cómo:

Solo oculta con conocimiento positivo. Si no sabemos qué sirve la flota (flota vacía, un Agent más antiguo que no reporta ningún connector), la superficie se muestra completa en lugar de desaparecer.
Sigue la salud, no solo la presencia. Un connector cuya credencial dejó de funcionar sale del conjunto servido, y las tools que dependían solo de él desaparecen (el mismo evento que reporta la salud de la flota).
Un análisis compuesto que cruza varias señales aparece si alguna de ellas está servida, y se degrada diciendo qué faltó. Ocultarlo por completo sería peor que entregarlo parcial y honesto. La excepción es la operación de entrada, sin la cual el análisis nunca empieza: esa sí lo hace desaparecer, en lugar de que se anuncie solo para fallar después.
El conjunto se decide cuando se abre la sesión. Un connector que vuelve a mitad de una investigación aparece en la siguiente sesión, no en esa.

Si de todos modos se llama a una tool oculta, el rechazo es inmediato y nombra las operaciones que nadie sirve, en lugar de mandar al agente a conectarse a algún lugar donde no hay credencial.

Descubrir lo que sirve tu flota

Tres superficies, que responden preguntas distintas:

Dónde	Qué responde
`tools/list`, desde tu propio cliente	Lo que esta sesión puede llamar. La respuesta autoritativa, ya filtrada por tu flota.
La tool `check_fleet_health`	Por qué falta algo: connector por connector, el estado en este momento.
La página Catálogo del control-plane	Lo que tiene el producto, sin importar tu flota. Útil para ver qué existiría si conectaras una fuente.

check_fleet_health es la que vale la pena aprender a leer, y está entre las tools que se anuncian desde el inicio de la sesión justamente para que sirva de preflight. Su vocabulario:

Estado	Significado
`up`	Servido y sano
`degraded`	Servido, con una parte fallando o cobertura incompleta
`down`	Servido, y todos los servidores con error (típicamente una credencial)
`unchecked`	Servido, pero sin sonda de credencial: este connector no expone una
`not_configured`	El Agent conoce la integración y no tiene credencial para ella (falta el secret)

Dos lecturas que te ahorran una investigación equivocada: unchecked no es “la sonda está atrasada”, es un connector que no trae ninguna sonda, así que esperar no va a cambiar el valor; y la frescura pertenece al rollup completo (checked_age_seconds, al inicio de la respuesta), no a cada connector.

Además de los connectors, devuelve un veredicto sobre toda la flota. Una flota sin ningún Agent conectado no se ve como una flota sana: lo dice en un campo propio, porque tres listas vacías se verían exactamente como “todo bien, nada degradado”.

`search_tools`: anunciar todo, o descubrir bajo demanda

Anunciar unos cuantos cientos de tools ocupa una porción grande del contexto del modelo antes de que haga nada. Hay un modo alternativo, desactivado por defecto:

Desactivado (por defecto). tools/list anuncia toda la superficie que sirve tu flota. Simple, compatible con cualquier cliente.
Activado. tools/list anuncia solo un núcleo curado más la meta-tool search_tools. El agente busca lo que necesita, las coincidencias pasan a poder llamarse en esa sesión, y el servidor emite tools/list_changed para que el cliente vuelva a pedir la lista.

Esa es la contrapartida: el modo activado ahorra contexto y cuesta un ida y vuelta de descubrimiento, y requiere un cliente que entienda tools/list_changed. Un cliente que ignore la notificación no verá las tools descubiertas en tools/list (el propio resultado de la búsqueda las nombra, así que el modelo igual puede llamarlas). Por eso el modo por defecto es el simple.

La búsqueda respeta el mismo gate: no va a ofrecer como “disponible ahora” una tool que tu flota no puede ejecutar.

Lecturas atómicas y análisis compuestos

La superficie tiene dos tipos de tool, y la diferencia es de altitud:

Las lecturas atómicas responden una pregunta contra una fuente: las métricas de un servicio, una ventana de logs, los security groups de una cuenta.
Los análisis compuestos responden una pregunta de investigación cruzando muchas lecturas: investiga este incidente, cómo está producción, cuál es el radio de impacto si este recurso se cae.

Lo que ganas al pedir el compuesto en lugar de coser los atómicos a mano no es solo comodidad. Es la correlación entre fuentes (el deploy que coincide con la caída, el vecino de topología que explica la latencia) y, sobre todo, la contabilidad de cobertura: el compuesto sabe cuántas fuentes deberían haber respondido y reporta las que no lo hicieron. Diecinueve lecturas sueltas no suman esa propiedad por sí solas.

La sesión se abre con contexto

Además de las tools, al abrir la sesión el servidor le entrega al modelo un contexto breve derivado de lo que ya se aprendió sobre tu entorno: la topología observada, las particularidades ya registradas y (cuando existen) la política de tu organización y qué backend de observabilidad sirve realmente a tu flota.

Ese último punto suena a detalle y no lo es: si no sabe que el que responde es SigNoz, y no Datadog, el modelo escribe consultas en el dialecto equivocado y recibe errores. Decirlo de entrada es más barato que dejar que lo descubra a prueba y error.

Las respuestas dicen lo que no pudieron ver

Esta es la propiedad más distintiva del producto, y probablemente la menos obvia en una primera lectura.

Toda respuesta trae un campo _sources: de qué fuentes vino y en qué estado respondió cada una. El vocabulario es cerrado, y cada palabra declara en cuál de cuatro clases cae: una lectura, una decisión deliberada de no preguntar, una imposibilidad de preguntar o ceguera. A partir de ahí, la forma de la respuesta cambia:

Fuente ciega: el cuerpo se descarta. Si fallaron todas las fuentes que deberían haber respondido, la respuesta no vuelve con ceros: vuelve como un sobre, con visibility: "none", error: "no_visibility" y un aviso que nombra las fuentes. Hasta la prosa se va, porque la prosa es justamente la parte que mentiría. Lo que sobrevive es el diagnóstico y los argumentos con los que se hizo la lectura, porque descartar el cuerpo no puede costarte saber sobre qué nos quedamos ciegos.
Cobertura parcial: el cuerpo se queda, anotado. Cuando hay datos reales, vuelven, con visibility: "partial" y una contabilidad de lo que faltó.
Lo vacío nunca se convierte en cero. Un conteo que vino de una operación que no respondió es null, no 0.
La ausencia exige prueba. Afirmar que algo no existe requiere una lectura que realmente haya ocurrido. Sin ella, el resultado es inconcluso, y lo dice.

Las dos primeras reglas son estructurales: se cumplen en un único punto, por el que pasa toda respuesta. Las dos últimas son la disciplina que cada tool mantiene dentro de su propio cuerpo. Esa es la diferencia entre una garantía sobre la forma y una regla sobre el contenido, y vale la pena conocerla para saber qué revisar cuando un número se ve demasiado bueno.

El mismo razonamiento rige los veredictos: una calificación, una clasificación, un “esto está bien”. Donde la calificación sale de penalizaciones, una lectura fallida mejoraría el número, así que la calificación simplemente no se emite cuando una fuente quedó ciega, y lo observado vuelve marcado como parcial. La ceguera total descarta el veredicto junto con el cuerpo; con cobertura parcial, contener la conclusión es tarea de cada tool.

Las lecturas tienen un alcance, y se declara

En la nube, toda lectura ocurre dentro de una cuenta (o proyecto, o tenant). Cuál se leyó viaja de vuelta en la respuesta en todas las nubes, y eso no es decoración: un Agent apuntado al lugar donde casi no hay nada es indistinguible de una cuenta vacía, a menos que alguien diga dónde miró. En AWS también vuelve la región, por la misma razón.

Cuando hay más de una cuenta enrutable, la tool te pide que elijas, o acepta barrerlas todas a la vez ("all"). Dos salvedades que conviene tener presentes antes de confiar en un barrido:

En AWS, declara lo que no barrió: las cuentas conocidas que están fuera del alcance de la flota aparecen nombradas y la visibilidad baja a parcial. Cuatro de quince cuentas nunca es una respuesta completa. En GCP y Magalu esa contabilidad todavía no existe: el barrido cubre lo que sirve la flota, sin enumerar lo que quedó fuera.
El barrido se detiene en 12 cuentas. Las demás vuelven listadas como omitidas, con el motivo. No desaparecen.

Quitar lecturas de la superficie

No toda lectura tiene que concederse. La denylist de tools es la forma de decir “puedes leer mis métricas y mis logs, pero no mis security groups”, compuesta por ti y aplicada por el Agent dentro de tu infra.

Lo que le pasa a la superficie cuando niegas algo:

Las tools que dependían solo de las operaciones negadas desaparecen del anuncio y de la ejecución.
Las que dependían de ellas en parte siguen, degradándose, y la respuesta trae una nota de que la política quitó parte de lo que habría visto.
La supresión es legible: la fuente negada se reporta como denied_by_policy, que cuenta como no pude leer y nunca como no existe. “La política me lo prohibió” no es prueba de ausencia, y esa distinción es la razón por la que la denylist no es una resta silenciosa.

La sesión también conoce la política antes de necesitarla, así que la respuesta a una pregunta en un área negada es “eso está desactivado por la política de tu organización” en lugar de “no encontré nada”. Lo que conoce es la política que el Agent anunció de vuelta. Una que compusiste y nunca desplegaste no aparece ahí, y por eso la Flota muestra el borrador y la versión aplicada lado a lado.

Lo que esta página no cubre

La lista de tools. Por decisión: se descubre, no se documenta. Consulta cómo descubrirla.
La escritura. Las cinco tools de escritura y los gates que las cubren están en lo que escribe el agente.
Lo que se redacta antes de que algo salga de tu infra: Redacción de PII.