SDK Python - Devin Docs

Esta documentação se destina às implantações federais do Devin. Voltar à documentação do Devin

O SDK Python (windsurf_analytics.py) é um cliente de linha de comando para os endpoints da API federal: relatórios de uso, consumo de ACU, gerenciamento de grupos e limites de ACU por usuário. Baixe o script na página Analytics do portal da sua implantação selecionando Download SDK ou entre em contato com seu representante da Cognition.

Requisitos

Python 3
Biblioteca requests: pip install requests

Autenticação

Todos os comandos aceitam estas flags comuns:

Flag	Descrição
`--service-key`	Chave de serviço para autenticação. Também pode ser definida pela variável de ambiente `WINDSURF_SERVICE_KEY`.
`--api-url`	URL base do servidor de API da sua implantação (`https://<your-server>`). HTTPS é obrigatório.

A função associada à chave de serviço deve ter a permissão exigida por cada comando — consulte a tabela de permissões. Todos os comandos de análises também exigem um nível de equipe com acesso à API de análises.

Comandos

Comando	Endpoint	Permissão necessária
`usage` (padrão)	`/UserPageAnalytics` + `/CascadeAnalytics`	Teams Read-Only
`acu-consumption`	`/Analytics`	Analytics Read
`list-groups`	`/ListGroups`	Teams Read-Only
`get-group`	`/GetGroup`	Teams Read-Only
`create-group`	`/CreateGroup`	Teams Update
`update-group`	`/UpdateGroup`	Teams Update
`delete-group`	`/DeleteGroup`	Teams Update
`list-group-members`	`/ListGroupMembers`	Teams Read-Only
`add-group-members`	`/AddGroupMembers`	Teams Update
`remove-group-members`	`/RemoveGroupMembers`	Teams Update
`get-user-acu-cap`	`/GetUserAcuCap`	Teams Read-Only
`update-user-acu-cap`	`/UpdateUserAcuCap`	Teams Update

A execução do script sem especificar um comando (a invocação original) gera o relatório de usage.

Saída e erros

Todos os comandos imprimem JSON em stdout. Os resultados paginados (linhas de usuários de consumo de ACU, list-groups, list-group-members) são buscados automaticamente até a última página e mesclados em uma única resposta. Os erros da API são impressos em stderr no formato Error calling <endpoint> (HTTP <status>): code: message, e o script é encerrado com o status 1. Combinações inválidas de flags são rejeitadas antes do envio de qualquer requisição, com status de saída 2.

Exemplos

Relatório de uso por usuário

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 ACUs

# Total de ACU da equipe mais linhas por usuário do ciclo de faturamento atual
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Detalhamento histórico por grupo (o intervalo deve ser de no máximo 90 dias),
# com linhas por usuário de um 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

Flags de acu-consumption: --current-cycle ou --start/--end selecionam o período; --include-team-total, --group-id repetível (máx. 100) e --team-user-rows / --group-user-rows GROUP_ID, mutuamente exclusivos, selecionam os dados; --page-size ajusta o tamanho da página por requisição (todas as páginas são buscadas de qualquer forma). É necessário usar pelo menos uma flag de seleção de dados. Uma chave com escopo de grupo pode selecionar apenas o grupo a ela atribuído e não pode solicitar totais da equipe nem linhas de usuários da equipe.

Gerenciamento de grupos

# Listar grupos e consultar um 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

# Criar um grupo e configurar seus modelos e o limite 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

# Remover a restrição de modelos ou o limite de ACU de um grupo. A API do serviço exige um
# valor positivo ao definir o limite de um grupo; a remoção é uma operação à parte.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Gerenciar associações (e-mails separados por vírgula, 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

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

Limites de ACU por usuário

# Consultar o limite configurado e o limite efetivo de um usuário (selecione por --email ou --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Definir um limite (0 bloqueia o usuário) ou remover o override
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

​Autenticação

​Comandos

​Saída e erros

​Exemplos

​Relatório de uso por usuário

​Consumo de ACUs

​Gerenciamento de grupos

​Limites de ACU por usuário

Requisitos

Autenticação

Comandos

Saída e erros

Exemplos

Relatório de uso por usuário

Consumo de ACUs

Gerenciamento de grupos

Limites de ACU por usuário