SDK de Python - Devin Docs

Esta documentación corresponde a los despliegues federales de Devin. Volver a la documentación de Devin

El SDK de Python (windsurf_analytics.py) es un cliente de línea de comandos para los endpoints de la API federal: informes de uso, consumo de ACU, gestión de grupos y límites de ACU por usuario. Ponte en contacto con tu representante de Cognition para obtener el script de tu despliegue.

Requisitos

Python 3
La biblioteca requests: pip install requests

Autenticación

Todos los comandos aceptan estas opciones compartidas:

Opción	Descripción
`--service-key`	Clave de servicio para la autenticación. También se puede configurar mediante la variable de entorno `WINDSURF_SERVICE_KEY`.
`--api-url`	URL base del servidor de API de tu despliegue (`https://<your-server>`). Se requiere HTTPS.

El rol de la clave de servicio debe contar con el permiso requerido por cada comando; consulta la tabla de permisos. Todos los comandos de analytics también requieren un tier de equipo con acceso a la Analytics API.

Comandos

Comando	Endpoint	Permiso requerido
`usage` (predeterminado)	`/UserPageAnalytics` + `/CascadeAnalytics`	Teams de solo lectura
`acu-consumption`	`/Analytics`	Analytics Read
`list-groups`	`/ListGroups`	Teams de solo lectura
`get-group`	`/GetGroup`	Teams de solo lectura
`create-group`	`/CreateGroup`	Teams Update
`update-group`	`/UpdateGroup`	Teams Update
`delete-group`	`/DeleteGroup`	Teams Update
`list-group-members`	`/ListGroupMembers`	Teams de solo lectura
`add-group-members`	`/AddGroupMembers`	Teams Update
`remove-group-members`	`/RemoveGroupMembers`	Teams Update
`get-user-acu-cap`	`/GetUserAcuCap`	Teams de solo lectura
`update-user-acu-cap`	`/UpdateUserAcuCap`	Teams Update

Al ejecutar el script sin especificar un comando (la invocación original), se ejecuta el informe de usage.

Salida y errores

Todos los comandos imprimen JSON en stdout. Los resultados paginados (filas de usuarios de consumo de ACU, list-groups, list-group-members) se recuperan automáticamente hasta la última página y se combinan en una única respuesta. Los errores de la API se imprimen en stderr con el formato code: message y el script finaliza con el código de estado 1.

Ejemplos

Informe de uso por usuario

python windsurf_analytics.py \
    --service-key YOUR_SERVICE_KEY \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z \
    --end 2025-03-31T23:59:59Z

Consumo de ACU

# Total de ACU del equipo más filas por usuario del ciclo de facturación actual
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Desglose histórico por grupo (la ventana no puede abarcar más de 90 días),
# con filas por usuario para un grupo
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z --end 2025-03-31T23:59:59Z \
    --group-id GROUP_A_ID --group-user-rows GROUP_A_ID

Opciones de acu-consumption: --current-cycle o --start/--end seleccionan el período; --include-team-total, --group-id repetible (máx. 100) y las opciones mutuamente excluyentes --team-user-rows / --group-user-rows GROUP_ID seleccionan los datos; --page-size ajusta el tamaño de página por solicitud (se recuperan todas las páginas de todos modos). Se requiere al menos una opción de selección de datos. Una clave limitada a un grupo solo puede seleccionar el grupo que tiene asignado y no puede solicitar totales del equipo ni filas de usuarios del equipo.

Gestión de grupos

# Listar grupos y consultar un grupo
python windsurf_analytics.py list-groups --api-url https://your-server.com
python windsurf_analytics.py get-group --api-url https://your-server.com \
    --group-id GROUP_ID

# Crear un grupo y configurar sus modelos y su límite de ACU
python windsurf_analytics.py create-group --api-url https://your-server.com \
    --name Engineering
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID \
    --cascade-models MODEL_UID_1,MODEL_UID_2 \
    --set-cycle-acu-limit 50

# Quitar la restricción de modelos o el límite de ACU de un grupo. La API del servicio
# exige un valor positivo al establecer el límite de un grupo; quitarlo es una operación aparte.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Gestionar la membresía (correos separados por comas, máx. 1000)
python windsurf_analytics.py add-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov,lead@agency.gov
python windsurf_analytics.py remove-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov

# Eliminar un grupo (idempotente)
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID

Límites de ACU por usuario

# Consulta el límite configurado y el efectivo de un usuario (selecciónalo con --email o --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Establece un límite (0 bloquea al usuario) o elimina la anulación
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --set-cycle-acu-limit 25
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --clear-cycle-acu-limit

​Requisitos

​Autenticación

​Comandos

​Salida y errores

​Ejemplos

​Informe de uso por usuario

​Consumo de ACU

​Gestión de grupos

​Límites de ACU por usuario

Requisitos

Autenticación

Comandos

Salida y errores

Ejemplos

Informe de uso por usuario

Consumo de ACU

Gestión de grupos

Límites de ACU por usuario