wehub-resource-sync
100 lines
5.2 KiB
Markdown
100 lines
5.2 KiB
Markdown
---
|
|
sidebar_position: 1
|
|
_i18n_hash: 3bea21234680fc0342392f5d9887ba15
|
|
---
|
|
# 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](https://agentskills.io/specification), consistente en un solo `SKILL.md` más archivos de referencia. Sin procesos de larga duración, sin runtime adicional.
|
|
|
|
:::tip Comienza
|
|
Consulta la [Guía de Instalación](./installation.md) 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](/docs/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/`](https://github.com/msgbyte/tianji/tree/master/skills/tianji-data-query). Se aceptan pull requests.
|