Integración con la Habilidad del Agente

Introducción

La Habilidad de Consulta de Datos Tianji es un conjunto de habilidades ligero y agnóstico al agente que permite a los agentes de IA (Cursor, Claude Code, Codex, Copilot CLI, etc.) consultar la plataforma Tianji directamente a través de su OpenAPI solo de lectura.

Sigue la especificación de agentskills.io, consistente en un solo SKILL.md más archivos de referencia. Sin procesos de larga duración, sin runtime adicional.

Comienza

Consulta la Guía de Instalación para la configuración en un clic o manual.

Lo que cubre: 69 endpoints GET en 14 dominios de servicio:

• Website — estadísticas de tráfico, vistas de página, distribución geográfica, informes de Lighthouse
• Monitor — estado de tiempo de actividad, datos de verificación recientes, eventos de monitoreo
• Survey — respuestas de encuestas, estadísticas de resultados, categorías de IA
• Telemetry — conteos de eventos personalizados, vistas de página de telemetría, métricas
• Feed — canales, flujos de eventos, estados de alimentación
• Application — reseñas de tiendas de aplicaciones, información de la aplicación, estadísticas de eventos
• Facturación / Gateway de IA / Trabajador / Página / Espacio de trabajo / Global / AuditLog

Habilidad vs Servidor MCP

Tianji ofrece dos formas de integrarse con agentes de IA. Elige la que se ajuste a tu flujo de trabajo:

	Habilidad del Agente	Servidor MCP
Forma	Archivos de documentación simple (SKILL.md + referencias)	Un proceso de Node.js de larga duración
Tiempo de ejecución	Ninguno — el agente utiliza curl o herramientas HTTP integradas	npx tianji-mcp-server
Cobertura	69 endpoints GET (solo lectura, superficie completa)	Un subconjunto curado de herramientas (lectura + algunas escrituras)
Configuración	Coloca los archivos en el directorio de habilidades del agente	Agrega configuración MCP al archivo de configuración del agente
Mejor para	Cursor / Claude Code / Codex / cualquier agente que siga la especificación agentskills.io	Agentes con soporte MCP de primera clase

Puedes utilizar ambos al mismo tiempo sin conflicto.

Ejemplos de Uso

Una vez instalado, puedes hacer preguntas en lenguaje natural a tu agente de IA y elegirá el endpoint correcto:

Ejemplo 1: Visión general del tráfico del sitio web

Usuario: Muéstrame las vistas de página de mi sitio web principal en los últimos 7 días.

Agente: [Llama a GET /open/workspace/{workspaceId}/website/all para encontrar el sitio]
       [Luego GET /open/workspace/{workspaceId}/website/{websiteId}/pageviews
        con startAt/endAt cubriendo 7 días]
       Tu sitio web principal recibió 12,438 vistas de página en los últimos 7 días,
       con un pico de 2,103 el martes. Principal referente: google.com (43%).

Ejemplo 2: Verificación de salud del monitor

Usuario: ¿Alguno de mis monitores está caído ahora mismo?

Agente: [Llama a GET /open/workspace/{workspaceId}/monitor/all]
       [Luego GET /open/workspace/{workspaceId}/monitor/{monitorId}/status
        para cada monitor]
       2 monitores están actualmente CAÍDOS:
       - api.example.com (HTTP 503, última vez ARRIBA hace 12 min)
       - db-replica (timeout TCP, última vez ARRIBA hace 1h)
       Los otros 8 monitores están en buen estado.

Ejemplo 3: Análisis de resultados de encuestas

Usuario: Resume las respuestas de la encuesta "Retroalimentación de Clientes del Q4".

Agente: [Llama a GET /open/workspace/{workspaceId}/survey/all para resolver el ID]
       [Luego GET /open/workspace/{workspaceId}/survey/{surveyId}/stats]
       [Luego GET /open/workspace/{workspaceId}/survey/{surveyId}/result/list
        con un cursor de paginación]
       "Retroalimentación de Clientes del Q4" recibió 218 respuestas. Satisfacción promedio
       4.3/5. Tema principal: rendimiento del panel (mencionado 47 veces). Función más
       solicitada: modo oscuro (31 menciones).

Manejo de Datos Sensibles

Algunos endpoints pueden devolver secretos almacenados en la plataforma (por ejemplo, modelApiKey, customModelBaseUrl en respuestas del Gateway de IA) o PII (miembros del espacio de trabajo, registros de auditoría, facturación).

La habilidad instruye a los agentes a:

• Nunca mostrar campos apiKey, modelApiKey, secret, token, password o credential.
• Redactar u omitir estos campos al resumir respuestas.
• Para miembros del espacio de trabajo / registros de auditoría, solo mostrar metadatos no sensibles (nombres, roles, marcas de tiempo) a menos que el usuario solicite explícitamente detalles completos.

El openapi-readonly.json incluido también pre-redacta estos campos a nivel de esquema, por lo que los agentes no pueden confiar accidentalmente en su estructura.

Fuente

La fuente de la habilidad se encuentra en el repositorio de Tianji bajo skills/tianji-data-query/. Se aceptan pull requests.