Como medir a adoção da janela de Agents do VS Code pela API de métricas do Copilot

Até 11/09/2026 não dava pra saber quantos devs do seu time realmente usavam a janela de Agents do VS Code

Dava pra ver uso genérico de Copilot, sim, mas aquela janela dedicada de agentes ficava misturada no bolo

Aí o GitHub soltou um changelog e a história mudou: os relatórios de métricas de uso do Copilot passaram a trazer campos específicos pra essa janela, em GA. Neste guia a gente vai do zero até uma planilha semanal: checar permissão, chamar o endpoint certo, baixar o relatório, parsear o formato (que NÃO é um JSON comum, já aviso) e cruzar sessões com mensagens pra separar quem só curioseou de quem incorporou na rotina

Bora?

O que mudou no changelog de 11 de setembro de 2026

O anúncio é o Add VS Code Agents to Copilot usage metrics, publicado em 11/09/2026

Ele marca como geralmente disponíveis as métricas de atividade da janela dedicada de Agents do VS Code dentro dos relatórios de uso do Copilot

A divisão é simples: relatório agregado te dá o total, relatório por usuário te dá o indivíduo

Nos relatórios agregados de enterprise e de organização, nos períodos de 1 dia e de 28 dias:

• <code>daily_active_vscode_agent_users</code>: contagem opcional de usuários únicos ativos na janela de Agents do VS Code por dia
• <code>totals_by_vscode_agent</code>: agregado opcional dos valores <code>session_count</code> e <code>total_user_messages</code>

Nos relatórios por usuário de enterprise e de organização, também em 1 dia e 28 dias:

• <code>used_vscode_agent</code>: indicador opcional de se aquele usuário usou a janela de Agents
• <code>totals_by_vscode_agent</code>: os mesmos <code>session_count</code> e <code>total_user_messages</code>, agora por pessoa

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Mas que janela de Agents é essa?

Pergunta justa, porque o VS Code tem chat, tem agente no editor, tem um monte de coisa

A janela de Agents é uma janela dedicada e agent-first: você atribui tarefas de alto nível e acompanha sessões de agentes entre workspaces, com lista de sessões, painel de customizações e uma área de chat com os painéis Changes e Files

A documentação oficial do VS Code chama ela de Use the Agents window (Preview), ou seja, o recurso ainda está marcado como Preview

Pra abrir, tem o botão Open in Agents na barra de título, ou o comando <code>Chat: Open Agents window</code> na Command Palette (Ctrl+Shift+P no Windows e Linux, Shift+Cmd+P no macOS)

E um registro de estado, porque isso importa quando o assunto é GA: até 13/09/2026 não houve reversão, correção ou atualização posterior ao anúncio

Os campos seguem publicados como geralmente disponíveis

Por que esses campos importam para quem lidera time

A sacada aqui não é o número em si, é conseguir separar duas coisas que sempre andam grudadas

Adoção é quanta gente abriu a janela: <code>daily_active_vscode_agent_users</code> no agregado, <code>used_vscode_agent</code> no nível do usuário

Engajamento é o que essa gente fez lá dentro: <code>session_count</code> e <code>total_user_messages</code> dentro de <code>totals_by_vscode_agent</code>

São perguntas diferentes, viu? Dez pessoas abrindo uma vez e sumindo é um cenário. Três pessoas com sessão todo dia é outro completamente diferente. Antes, os dois viravam a mesma linha no relatório

Com o agregado você acompanha tendência ao longo do tempo, e com o relatório por usuário você entende como o uso se distribui entre times

Isso ajuda demais na hora de justificar licença, planejar habilitação e enxergar se aquele treinamento interno virou hábito ou virou nada

O que esses números NÃO dizem

Aqui é onde muita gente se ferra ao montar dashboard, então deixo claro logo de cara

Primeiro: as métricas cobrem apenas a janela dedicada de Agents. Elas permanecem separadas do Agent Mode da janela do editor e dos rollups genéricos de uso

Se metade do time usa agente dentro do editor mesmo, esse uso não vai aparecer nesses campos, e o gráfico vai parecer pior do que a realidade

Segundo: nenhum desses campos mede qualidade

<code>total_user_messages</code> alto pode ser produtividade, pode ser o dev brigando com o agente por vinte mensagens pra resolver uma coisa simples

O dado não distingue, e quem interpreta é você

Pré-requisitos de acesso e permissão antes de chamar a API

Antes de escrever qualquer linha de código, confere estes pontos. Dá pra economizar uma tarde de depuração de 403

1. Quem pode ver

O acesso está disponível a donos de enterprise e billing managers, donos de organização, e a quem tiver uma função personalizada de organização ou de enterprise que conceda View Copilot Metrics

Se você não está em nenhuma dessas caixas, o caminho é pedir a função, não tentar contornar

2. A política precisa estar habilitada

A política de métricas de uso do Copilot tem que estar ligada pra que os dados fiquem disponíveis

Sem isso, a API não vai te entregar relatório nenhum, por mais permissão que você tenha

3. Permissões granulares por escopo

Na API, as permissões nomeadas são View Organization Copilot Metrics pro escopo de organização e View Enterprise Copilot Metrics pro escopo de enterprise

4. Escopos do token

Pra tokens de OAuth app e personal access tokens (classic):

5. Janela de dados disponível

Os relatórios de métricas de uso do Copilot estão disponíveis a partir de 10 de outubro de 2025, com histórico de até 1 ano a partir da data atual

Ou seja: não adianta tentar puxar dado de 2024 pra montar comparação histórica, ele simplesmente não existe por ali

A referência que vale pra tudo isso é a documentação de REST API endpoints for Copilot usage metrics, que é o ponto de partida indicado pelo próprio comunicado

Passo a passo: da chamada na API à planilha semanal de adoção

Agora a parte prática

Vou seguir a ordem real do trabalho: pega o link, baixa, parseia, escolhe o relatório certo, trata o que vem vazio e joga na planilha

1. Monte a rota do relatório conforme o seu escopo

O caminho dos endpoints segue o padrão de escopo mais o nome do relatório:

<pre><code>GET /orgs/{org}/copilot/metrics/reports/{report_name} GET /enterprises/{enterprise}/copilot/metrics/reports/{report_name} </code></pre>

O erro comum deste passo é chutar o <code>{report_name}</code>

Abra a lista de nomes de relatório na documentação oficial da API e use o nome exato que estiver lá

2. Leia a resposta: ela não é o relatório, é o caminho pro relatório

Esse é o ponto que pega quase todo mundo na primeira vez

Os relatórios são gerados diariamente e disponibilizados para download por meio de URLs assinadas com expiração limitada. A resposta da API traz os links de download e a data do relatório

Se você conhece aquele fluxo de bucket com link temporário, é exatamente a mesma ideia: a API te dá a chave, o arquivo está do outro lado

<pre><code>curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer $GITHUB_TOKEN" \ https://api.github.com/orgs/MINHA_ORG/copilot/metrics/reports/NOME_DO_RELATORIO </code></pre>

O erro comum deste passo é esperar os campos de métrica direto nessa resposta e concluir que o recurso não funciona

Não é isso: você recebeu o ponteiro, precisa seguir ele

3. Baixe o arquivo e parseie como NDJSON, linha a linha

Os arquivos de relatório são NDJSON (JSON delimitado por linha), e não um único array ou objeto JSON

Tome cuidado aqui! O erro comum deste passo é jogar <code>json.load()</code> no arquivo inteiro e tomar exceção de parsing logo na segunda linha

O jeito certo é iterar:

<pre><code>import json

registros = []

with open("relatorio.ndjson", "r", encoding="utf-8") as f: for linha in f: linha = linha.strip() if not linha: continue registros.append(json.loads(linha))

print(len(registros)) </code></pre>

4. Escolha o relatório certo pra pergunta que você tem

Aqui a documentação de referência é bem clara sobre o desenho de cada um:

O erro comum deste passo é procurar <code>daily_active_vscode_agent_users</code> no relatório por usuário, ou procurar <code>used_vscode_agent</code> no agregado

Não está faltando dado: cada relatório foi desenhado pra uma granularidade

5. Desembrulhe o relatório de 28 dias antes de iterar

Os relatórios de 28 dias são invólucros: carregam a janela de apuração no nível superior e um array de registros agregados diários

Então o loop tem dois níveis, não um

<pre><code>linhas_diarias = []

for registro in registros: diarios = registro.get("daily_metrics") or [] for dia in diarios: linhas_diarias.append(dia) </code></pre>

O erro comum deste passo é tratar o registro de 28 dias como se fosse um dia só e acabar com uma planilha de uma linha

Confira na documentação o nome exato da chave do array antes de fixar no código

6. Trate os campos opcionais que vêm ausentes ou nulos

O comportamento de dado ausente é retrocompatível: os campos opcionais continuam ausentes ou nulos quando não há dado correspondente da janela de Agents do VS Code

Ou seja, <code>daily_active_vscode_agent_users</code> pode simplesmente não existir naquele registro, e <code>totals_by_vscode_agent</code> pode vir nulo

Acesso direto por chave quebra o pipeline inteiro por causa de um dia sem dado

<pre><code>def pega(registro, chave, padrao=None): valor = registro.get(chave) return padrao if valor is None else valor

ativos = pega(dia, "daily_active_vscode_agent_users", 0) totais = pega(dia, "totals_by_vscode_agent", {}) </code></pre>

O erro comum deste passo é confundir ausente com zero na hora de ler o gráfico

Ausente significa "não tem dado", zero significa "ninguém usou". Guarde os dois de forma distinta se a diferença importar pro seu relatório

Sobre o formato exato do objeto <code>totals_by_vscode_agent</code> no JSON: o comunicado cita apenas os valores <code>session_count</code> e <code>total_user_messages</code>, então inspecione a estrutura real que chegou antes de assumir o shape no seu código

7. Monte as colunas da planilha

Com os registros na mão, a planilha semanal sai de forma direta

<pre><code>import csv

with open("adocao_semanal.csv", "w", newline="", encoding="utf-8") as f: w = csv.writer(f) w.writerow(["data", "usuarios_ativos", "sessoes", "mensagens"]) for dia in linhas_diarias: totais = pega(dia, "totals_by_vscode_agent", {}) w.writerow([ dia.get("date"), pega(dia, "daily_active_vscode_agent_users", ""), totais.get("session_count", ""), totais.get("total_user_messages", ""), ]) </code></pre>

O erro comum deste passo é automatizar o job antes de rodar uma coleta manual e olhar o arquivo com o olho

Rode uma vez, abra o CSV, confira se as colunas bateram. Depois agenda

Como ler os números: quem experimentou x quem incorporou na rotina

Agora a parte que realmente muda decisão

O relatório por usuário te dá três coisas na mesma linha: <code>used_vscode_agent</code>, <code>session_count</code> e <code>total_user_messages</code>

Cruzando os três, dá pra montar leituras que o número solto não entrega:

• <code>used_vscode_agent</code> verdadeiro, poucas sessões, poucas mensagens: a pessoa abriu, olhou e não voltou. É teste pontual
• <code>used_vscode_agent</code> verdadeiro, sessões recorrentes ao longo dos dias: aí sim tem sinal de rotina, porque o retorno se repete
• Poucas sessões, mas muitas mensagens dentro delas: a pessoa está indo fundo em cada sessão. Não é abandono, é outro padrão de uso

Repare que em nenhuma dessas leituras eu falei "bom" ou "ruim"

Não existe número de referência publicado pra comparar, então o que você tem é a sua própria série temporal: a semana 2 contra a semana 1, e por aí vai

É por isso que a primeira coleta é a mais importante. Ela é a sua linha de base

Quebrando a adoção por time

O relatório por usuário sozinho te dá uma lista de logins, o que é pouco útil quando o time tem dezenas de pessoas

Pra resolver isso existem os relatórios de mapeamento de usuários para times, no padrão <code>*-user-teams-1-day</code>, que mapeiam usuários aos times a que pertencem

Com esse join você sai de "um monte de gente usou" pra "o time de plataforma adotou, o time de mobile não encostou", que é uma conversa bem diferente de se ter

E já que estamos falando de acesso de time a ferramenta de agente, esse mesmo tipo de dor aparece em outros contextos: vale olhar como dar acesso ao time sem chave individual resolve o lado da distribuição

Campos vazios, relatório sem dado e outros tropeços comuns

Separei os sintomas que mais confundem, com a causa real e o que fazer

Os campos de VS Code Agents não aparecem no meu relatório

Causa provável: não há dado correspondente da janela de Agents naquele período. Os campos opcionais permanecem ausentes ou nulos quando o dado não está disponível, e isso é comportamento retrocompatível esperado

Como prevenir: escreva o parser assumindo ausência desde o dia um, com <code>.get()</code> e valor padrão, nunca com acesso direto por chave

O relatório agregado não tem <code>user_id</code> nem <code>used_*</code>

Causa: é o desenho do relatório, não bug. Os relatórios agregados trazem um registro agregado por escopo com contagens de usuários ativos, e não contêm <code>user_id</code>, <code>user_login</code> nem os indicadores <code>used_*</code>

Como prevenir: decida a granularidade antes de escolher o relatório. Pergunta de total vai no agregado, pergunta de pessoa vai no relatório por usuário

O relatório por usuário não tem contagem de ativos

Causa: mesma lógica invertida. Os relatórios por usuário trazem um registro por usuário e não contêm contagens de usuários ativos

Como prevenir: se você precisa do número de ativos por dia, puxe o agregado. Se precisa dos dois, puxe os dois e junte na sua planilha

Link de download falhando

Causa provável: as URLs de download são assinadas e têm expiração limitada

Como prevenir: no seu script, chame o endpoint e baixe o arquivo na mesma execução, sem guardar a URL pra usar depois. Se precisar reprocessar, chame a API de novo pra gerar um link fresco

403 ou 404 ao chamar o endpoint

Causa provável: escopo de token insuficiente ou política desabilitada

Como prevenir: confira se o token tem <code>read:org</code> pro endpoint de organização, ou <code>manage_billing:copilot</code> ou <code>read:enterprise</code> pro endpoint de enterprise. Depois confirme se a política de métricas de uso do Copilot está habilitada e se a sua conta tem View Organization Copilot Metrics ou View Enterprise Copilot Metrics conforme o escopo

Pedi uma data e voltou vazio

Causa provável: data fora da janela disponível. Os relatórios existem a partir de 10 de outubro de 2025, com histórico de até 1 ano a partir da data atual

Como prevenir: limite o range do seu script à janela válida antes de sair pedindo mês a mês

Conclusão

O changelog de 11/09/2026 resolveu uma cegueira bem específica: agora dá pra separar, com dado, quem abriu a janela de Agents do VS Code de quem passou a trabalhar nela

O caminho é o mesmo sempre: permissão em ordem, chamada no endpoint de relatório, link assinado, NDJSON parseado linha a linha, campos opcionais tratados com carinho e planilha montada

Mas mantenha os limites na cabeça na hora de apresentar esses números

A cobertura é só da janela dedicada, separada do Agent Mode da janela do editor e dos rollups genéricos, e nenhum campo aqui diz se o resultado do agente prestou

Próximo passo prático: abra a documentação de REST API endpoints for Copilot usage metrics e confirme os nomes exatos de relatório e de campo antes de automatizar qualquer coisa

Depois roda a coleta por uma semana inteira, sem tirar conclusão nenhuma ainda

Essa primeira semana é a sua linha de base, e sem ela todo número que vier depois é só um número solto

E se a sua praia é outra ferramenta de agente, o raciocínio de instrumentar antes de escalar vale igual: configuração de MCP, skills e subagents segue a mesma lógica de arrumar a casa antes de soltar pro time

Até o próximo post! 🙂