API de métricas do Copilot passa a detalhar uso por agente

O GitHub anunciou no changelog uma mudança pequena no tamanho, mas relevante para quem precisa justificar (ou cortar) gasto com IA: a Copilot usage metrics API agora reporta a atividade de apps agentes discriminada por agente individual. Antes, todo o trabalho feito via agentes caía num único bucket, sem distinguir o Copilot coding agent de outros agentes como Claude ou Codex rodando dentro dos workflows do GitHub.

O que mudou na prática

Os relatórios de 1 dia e 28 dias, nos escopos enterprise, organization, enterprise-user e organization-user, ganharam um array opcional chamado totals_by_3rd_party_agent. Cada entrada representa um agente reconhecido e traz quatro campos:

• agent_name: nome de exibição do agente. Segundo o próprio GitHub, esse nome pode mudar, então não use ele como chave.
• agent_id: identificador estável. É por ele que você deve agrupar e fazer join entre períodos.
• user_initiated_interaction_count: número de job starts de apps agentes iniciados por usuário.
• session_count: número de sessões, presente apenas nos relatórios agregados de enterprise e organization. As entradas por usuário omitem esse campo.

A mudança é retrocompatível. Campos existentes mantêm o formato, e o array totals_by_3rd_party_agent some por completo quando não há atividade de agente reconhecida no período. Ou seja: seu parser atual não quebra, mas precisa passar a tratar a presença opcional do novo campo.

A pegadinha do campo homônimo

Aqui mora o detalhe que vai gerar bug em pipeline mal revisado. Existe um user_initiated_interaction_count aninhado dentro de cada agente, que conta job starts de apps agentes, e existe um campo de mesmo nome no nível superior, que conta prompts explícitos vindos de outra telemetria. O GitHub é enfático: "Do not sum the two or treat them as interchangeable."

Na prática, se o seu ETL faz um flatten ingênuo do JSON e soma tudo que se chama user_initiated_interaction_count, você vai inflar a métrica e tomar decisão de licenciamento em cima de número errado. Vale escrever um teste que garanta que os dois níveis são lidos e contabilizados separadamente.

Outro ponto de atenção na modelagem: a atividade é agregada por agente, então múltiplos apps que pertencem ao mesmo agente colapsam numa entrada só. E atividade de agentes que o GitHub não consegue identificar simplesmente não aparece, o que significa que a soma dos agentes reportados não necessariamente fecha com o total de atividade de agentes da organização.

Por que isso importa para quem integra IA

O valor está em responder perguntas básicas que antes eram chute: quais agentes as pessoas realmente usam, por quanta gente, e como a adoção de um agente recém-liberado se compara ao que ele deveria complementar. Para times que estão empilhando ferramentas de IA, isso transforma decisão de rollout e de contrato de "achismo" em dado de uso real.

Do ponto de vista de arquitetura de observabilidade, é o mesmo raciocínio de sempre: métrica agregada esconde comportamento, métrica dimensionada revela. Trocar um contador único por um breakdown por agent_id é o equivalente a adicionar um label num contador Prometheus. O custo é lidar com cardinalidade e com a semântica de cada dimensão, e é exatamente aí que a documentação de campos ajuda a não errar.

Quem vê e quando não vale a pena

O acesso é para enterprise owners, billing managers, organization owners e quem tiver role customizada com a permissão View Copilot Metrics. A política de Copilot usage metrics precisa estar habilitada.

Uma ressalva pragmática: se a sua organização usa um único agente, o breakdown adiciona pouco além de ruído de parsing, então talvez não valha reescrever ingestão só por causa disso agora. O ganho aparece quando há dois ou mais agentes concorrendo pelo mesmo orçamento. Para começar, o GitHub aponta a documentação da usage metrics API e a referência de campos de métricas de apps agentes.

Fonte: GitHub Changelog