Métricas de uso e cobrança

Dica

Cada exemplo é funcionalmente equivalente entre idiomas. O trecho de código em TypeScript é expandido por padrão; selecione seu idioma nos blocos expansíveis para ver a mesma lógica nesse SDK.

Visão Geral

O SDK apresenta dados de uso por meio de dois mecanismos complementares:

Eventos de sessão: eventos efêmeros que o ambiente de execução emite durante a execução de um turno. Assine estes para obter dados em tempo real por chamada de API.
Métodos RPC: chamadas de solicitação/resposta feitas sob demanda. Use-os para registrar os totais acumulados ou consultar a cota da conta.

A tabela abaixo mapeia cada sinal para a API que o expõe.

Sinal	API	Scope	Tipo
Contagem de tokens por chamada
evento `assistant.usage`	Session	Event
Utilização da janela de contexto
evento `session.usage_info`	Session	Event
Detalhamento da janela de contexto (sob demanda)	`session.metadata.contextInfo`	Session	RPC
Totais acumulados de créditos de IA e tokens	`session.usage.getMetrics`	Session	RPC
Preços de crédito de IA por modelo	`models.list`	Servidor	RPC
Quota da conta e interações premium	`account.getQuota`	Servidor	RPC

Observação

session.usage.getMetrics, session.metadata.contextInfoe session.metadata.recomputeContextTokens são marcados como experimentais na superfície RPC gerada. Em .NET, é gerado o diagnóstico experimental GHCP001, que você suprime com #pragma warning disable GHCP001 ou com uma <NoWarn>GHCP001</NoWarn> no nível do projeto. Fixe o SDK e o runtime da CLI Copilot se o aplicativo depender deles.

As tabelas de campo abaixo listam apenas os campos usados nos exemplos nesta página. A referência completa e sempre atualizada dos campos consiste nos tipos gerados do SDK e em Eventos de sessão de streaming, que é regenerado a partir do esquema da CLI a cada atualização de dependência. Trate-os como a fonte da verdade e esta página como um guia orientado para tarefas.

Contagem de tokens por chamada

O evento assistant.usage é emitido uma vez para cada chamada à API do modelo em uma rodada (incluindo chamadas feitas por sub-agentes). Ele inclui a contagem de tokens e o multiplicador de cobrança para essa chamada específica.

O exemplo a seguir usa esses campos. Consulte Eventos de sessão de streaming para obter a lista completa, incluindo cache, raciocínio, latência e campos de rastreamento.

Campo	Tipo	Description
`model`	`string`	Identificador de modelo para esta chamada
`inputTokens`	`number`	Tokens de entrada consumidos
`outputTokens`	`number`	Tokens de saída produzidos
`cost`	`number`	Multiplicador de solicitação Premium aplicado a essa chamada

Dica

assistant.usage é efêmero, portanto é transmitido ao vivo, mas não é reproduzido ao retomar uma sessão. Para ler os totais acumulados posteriormente, chame session.usage.getMetrics (consulte Totais acumulados de créditos de IA e tokens).

Idiomas de código navigation

TypeScript

session.on("assistant.usage", (event) => {
    const { model, inputTokens, outputTokens, cost } = event.data;
    console.log(
        `${model}: in=${inputTokens ?? 0} out=${outputTokens ?? 0} cost=${cost ?? 0}`,
    );
});

Python

def on_usage(event):
    if event.type == SessionEventType.ASSISTANT_USAGE:
        data = event.data
        print(f"{data.model}: in={data.input_tokens or 0} out={data.output_tokens or 0} cost={data.cost or 0}")

session.on(on_usage)

session.On(func(event copilot.SessionEvent) {
    d, ok := event.Data.(*copilot.AssistantUsageData)
    if !ok {
        return
    }
    in, out, cost := int64(0), int64(0), float64(0)
    if d.InputTokens != nil {
        in = *d.InputTokens
    }
    if d.OutputTokens != nil {
        out = *d.OutputTokens
    }
    if d.Cost != nil {
        cost = *d.Cost
    }
    fmt.Printf("%s: in=%d out=%d cost=%g\n", d.Model, in, out, cost)
})

.NET

session.On<AssistantUsageEvent>(evt =>
{
    var data = evt.Data;
    Console.WriteLine(
        $"{data.Model}: in={data.InputTokens ?? 0} out={data.OutputTokens ?? 0} cost={data.Cost ?? 0}");
});

Java

session.on(AssistantUsageEvent.class, event -> {
    var data = event.getData();
    long in = data.inputTokens() != null ? data.inputTokens() : 0;
    long out = data.outputTokens() != null ? data.outputTokens() : 0;
    double cost = data.cost() != null ? data.cost() : 0.0;
    System.out.printf("%s: in=%d out=%d cost=%s%n", data.model(), in, out, cost);
});

Rust

use github_copilot_sdk::session_events::AssistantUsageData;

let mut events = session.subscribe();
while let Ok(event) = events.recv().await {
    if event.event_type == "assistant.usage" {
        if let Some(data) = event.typed_data::<AssistantUsageData>() {
            println!(
                "{}: in={} out={} cost={}",
                data.model,
                data.input_tokens.unwrap_or(0),
                data.output_tokens.unwrap_or(0),
                data.cost.unwrap_or(0.0),
            );
        }
    }
}

Utilização da janela de contexto

As contagens de tokens informam o que cada chamada consumiu. A utilização da janela de contexto indica o nível de ocupação da janela de contexto do modelo no momento — útil para exibir uma barra de progresso ou avisar o usuário antes que a compactação automática seja acionada.

Atualizações em tempo real com `session.usage_info`

O runtime emite um session.usage_info evento sempre que o tamanho da janela de contexto é alterado. O exemplo usa currentTokens e tokenLimit; consulte Eventos de sessão de streaming para a carga completa.

Campo	Tipo	Description
`currentTokens`	`number`	Tokens atualmente na janela de contexto
`tokenLimit`	`number`	Tokens máximos para a janela de contexto do modelo

Idiomas de código navigation

TypeScript

session.on("session.usage_info", (event) => {
    const { currentTokens, tokenLimit } = event.data;
    const pct = Math.round((currentTokens / tokenLimit) * 100);
    console.log(`Context: ${currentTokens}/${tokenLimit} (${pct}%)`);
});

Python

def on_usage_info(event):
    if event.type == SessionEventType.SESSION_USAGE_INFO:
        data = event.data
        pct = round(data.current_tokens / data.token_limit * 100)
        print(f"Context: {data.current_tokens}/{data.token_limit} ({pct}%)")

session.on(on_usage_info)

session.On(func(event copilot.SessionEvent) {
    d, ok := event.Data.(*copilot.SessionUsageInfoData)
    if !ok {
        return
    }
    pct := int(float64(d.CurrentTokens) / float64(d.TokenLimit) * 100)
    fmt.Printf("Context: %d/%d (%d%%)\n", d.CurrentTokens, d.TokenLimit, pct)
})

.NET

session.On<SessionUsageInfoEvent>(evt =>
{
    var pct = (int)Math.Round((double)evt.Data.CurrentTokens / evt.Data.TokenLimit * 100);
    Console.WriteLine($"Context: {evt.Data.CurrentTokens}/{evt.Data.TokenLimit} ({pct}%)");
});

Java

session.on(SessionUsageInfoEvent.class, event -> {
    var data = event.getData();
    long pct = Math.round((double) data.currentTokens() / data.tokenLimit() * 100);
    System.out.printf("Context: %d/%d (%d%%)%n", data.currentTokens(), data.tokenLimit(), pct);
});

Rust

use github_copilot_sdk::session_events::SessionUsageInfoData;

let mut events = session.subscribe();
while let Ok(event) = events.recv().await {
    if event.event_type == "session.usage_info" {
        if let Some(data) = event.typed_data::<SessionUsageInfoData>() {
            let pct = (data.current_tokens as f64 / data.token_limit as f64 * 100.0) as i64;
            println!("Context: {}/{} ({}%)", data.current_tokens, data.token_limit, pct);
        }
    }
}

Detalhamento sob demanda com `session.metadata.contextInfo`

Os eventos só são acionados quando o contexto é alterado. Para ler o detalhamento atual a qualquer momento, por exemplo, logo após retomar uma sessão, use session.metadata.contextInfo. Passe 0 em promptTokenLimit para usar o padrão do tempo de execução; passe 0 em outputTokenLimit se o valor for desconhecido.

O resultado contextInfo é null até que a sessão tenha sido inicializada (o prompt do sistema e os metadados de ferramenta foram armazenados em cache). Ele divide o total em systemTokens, conversationTokense toolDefinitionsTokens, ao lado do promptTokenLimit.

Idiomas de código navigation

TypeScript

const { contextInfo } = await session.rpc.metadata.contextInfo({
    promptTokenLimit: 0,
    outputTokenLimit: 0,
});

if (contextInfo) {
    console.log(
        `Total ${contextInfo.totalTokens}/${contextInfo.promptTokenLimit} ` +
            `(system=${contextInfo.systemTokens}, conversation=${contextInfo.conversationTokens})`,
    );
}

Python

result = await session.rpc.metadata.context_info(
    MetadataContextInfoRequest(prompt_token_limit=0, output_token_limit=0)
)
info = result.context_info

if info is not None:
    print(
        f"Total {info.total_tokens}/{info.prompt_token_limit} "
        f"(system={info.system_tokens}, conversation={info.conversation_tokens})"
    )

result, _ := session.RPC.Metadata.ContextInfo(ctx, &rpc.MetadataContextInfoRequest{
    PromptTokenLimit: 0,
    OutputTokenLimit: 0,
})

if info := result.ContextInfo; info != nil {
    fmt.Printf("Total %d/%d (system=%d, conversation=%d)\n",
        info.TotalTokens, info.PromptTokenLimit, info.SystemTokens, info.ConversationTokens)
}

.NET

var result = await session.Rpc.Metadata.ContextInfoAsync(promptTokenLimit: 0, outputTokenLimit: 0);
var info = result.ContextInfo;

if (info is not null)
{
    Console.WriteLine(
        $"Total {info.TotalTokens}/{info.PromptTokenLimit} " +
        $"(system={info.SystemTokens}, conversation={info.ConversationTokens})");
}

Java

var result = session.getRpc().metadata
    .contextInfo(new SessionMetadataContextInfoParams(null, 0L, 0L, null))
    .join();
var info = result.contextInfo();

if (info != null) {
    System.out.printf("Total %d/%d (system=%d, conversation=%d)%n",
        info.totalTokens(), info.promptTokenLimit(), info.systemTokens(), info.conversationTokens());
}

Rust

use github_copilot_sdk::rpc::MetadataContextInfoRequest;

let result = session
    .rpc()
    .metadata()
    .context_info(MetadataContextInfoRequest {
        prompt_token_limit: 0,
        output_token_limit: 0,
        selected_model: None,
    })
    .await?;

if let Some(info) = result.context_info {
    println!(
        "Total {}/{} (system={}, conversation={})",
        info.total_tokens, info.prompt_token_limit, info.system_tokens, info.conversation_tokens,
    );
}

Totais acumulados de créditos de IA e tokens

session.usage.getMetrics retorna os totais acumulados de toda a sessão em uma única chamada. Essa é a maneira mais limpa de ler o custo de crédito de IA, pois agrega todas as chamadas à API (agente principal e subagentes) para você.

O exemplo usa os campos abaixo. O tipo gerado UsageGetMetricsResult é a referência completa.

Campo	Tipo	Description
`totalNanoAiu`	`number`	Custo de crédito de IA em toda a sessão, em unidades de IA nano
`totalPremiumRequestCost`	`number`	Custo da solicitação premium entre todos os modelos, após a aplicação dos multiplicadores
`modelMetrics`	`Record<string, ModelMetric>`	Detalhamento por modelo; cada entrada tem `usage.inputTokens`, `usage.outputTokens`e `totalNanoAiu`

Observação

O custo é relatado em unidades nano-IA (o campo é nomeado totalNanoAiu). A conversão exata em créditos de IA e o significado preciso da contabilização de solicitações premium são definidos pela cobrança do GitHub Copilot, não pelo SDK — trate a documentação de cobrança do GitHub Copilot como fonte de referência e verifique isso antes de exibir valores monetários aos usuários. Os exemplos usam a divisão por 1e9 por conveniência, seguindo o prefixo nano do SI; confirme se isso corresponde à cobrança atual antes de confiar nisso. Os mapas modelMetrics e tokenDetails são indexados por strings de tempo de execução (IDs de modelo e nomes de tipos de token) que o sistema de tipos do SDK não valida.

Idiomas de código navigation

TypeScript

const metrics = await session.rpc.usage.getMetrics();

const aiCredits = (metrics.totalNanoAiu ?? 0) / 1e9;
console.log(`AI credits used: ${aiCredits.toFixed(6)}`);
console.log(`Premium requests: ${metrics.totalPremiumRequestCost}`);

for (const [model, m] of Object.entries(metrics.modelMetrics)) {
    if (!m) continue;
    console.log(
        `${model}: in=${m.usage.inputTokens} out=${m.usage.outputTokens} ` +
            `nanoAiu=${m.totalNanoAiu ?? 0}`,
    );
}

Python

metrics = await session.rpc.usage.get_metrics()

ai_credits = (metrics.total_nano_aiu or 0) / 1e9
print(f"AI credits used: {ai_credits:.6f}")
print(f"Premium requests: {metrics.total_premium_request_cost}")

for model, m in metrics.model_metrics.items():
    print(f"{model}: in={m.usage.input_tokens} out={m.usage.output_tokens} nanoAiu={m.total_nano_aiu or 0}")

metrics, _ := session.RPC.Usage.GetMetrics(ctx)

aiCredits := float64(0)
if metrics.TotalNanoAiu != nil {
    aiCredits = *metrics.TotalNanoAiu / 1e9
}
fmt.Printf("AI credits used: %.6f\n", aiCredits)
fmt.Printf("Premium requests: %v\n", metrics.TotalPremiumRequestCost)

for model, m := range metrics.ModelMetrics {
    nanoAiu := float64(0)
    if m.TotalNanoAiu != nil {
        nanoAiu = *m.TotalNanoAiu
    }
    fmt.Printf("%s: in=%d out=%d nanoAiu=%v\n", model, m.Usage.InputTokens, m.Usage.OutputTokens, nanoAiu)
}

.NET

var metrics = await session.Rpc.Usage.GetMetricsAsync();

var aiCredits = (metrics.TotalNanoAiu ?? 0) / 1e9;
Console.WriteLine($"AI credits used: {aiCredits:F6}");
Console.WriteLine($"Premium requests: {metrics.TotalPremiumRequestCost}");

foreach (var (model, m) in metrics.ModelMetrics)
{
    Console.WriteLine(
        $"{model}: in={m.Usage.InputTokens} out={m.Usage.OutputTokens} nanoAiu={m.TotalNanoAiu ?? 0}");
}

Java

var metrics = session.getRpc().usage.getMetrics().join();

double aiCredits = metrics.totalNanoAiu() != null ? metrics.totalNanoAiu() / 1e9 : 0;
System.out.printf("AI credits used: %.6f%n", aiCredits);
System.out.printf("Premium requests: %s%n", metrics.totalPremiumRequestCost());

metrics.modelMetrics().forEach((model, m) -> {
    double nanoAiu = m.totalNanoAiu() != null ? m.totalNanoAiu() : 0;
    System.out.printf("%s: in=%d out=%d nanoAiu=%s%n",
        model, m.usage().inputTokens(), m.usage().outputTokens(), nanoAiu);
});

Rust

let metrics = session.rpc().usage().get_metrics().await?;

let ai_credits = metrics.total_nano_aiu.unwrap_or(0.0) / 1e9;
println!("AI credits used: {ai_credits:.6}");
println!("Premium requests: {}", metrics.total_premium_request_cost);

for (model, m) in &metrics.model_metrics {
    let nano_aiu = m.total_nano_aiu.unwrap_or(0.0);
    println!(
        "{model}: in={} out={} nanoAiu={nano_aiu}",
        m.usage.input_tokens, m.usage.output_tokens,
    );
}

Preços de crédito de IA por modelo

Para estimar o custo antes de executar uma interação, leia os preços por token de cada modelo em models.list. Esta é uma chamada com escopo de servidor feita pelo cliente, portanto não requer sessão. Os preços são expressos em créditos de IA por lote de cobrança de tokens. O tipo gerado ModelBillingTokenPrices lista todos os campos, incluindo cachePrice.

Campo	Tipo	Description
`billing.multiplier`	`number`	Multiplicador de custo de solicitação Premium em relação à taxa base
`billing.tokenPrices.inputPrice`	`number`	Custo de crédito de IA por lote de tokens de entrada
`billing.tokenPrices.outputPrice`	`number`	Custo de créditos de IA por lote de tokens de saída
`billing.tokenPrices.batchSize`	`number`	Número de tokens por lote de cobrança

Observação

Os valores de preço mudam à medida que os planos e os modelos evoluem. Leia-os em tempo de execução, conforme mostrado abaixo; nunca codifique os números diretamente no seu aplicativo.

Idiomas de código navigation

TypeScript

const { models } = await client.rpc.models.list({});

for (const model of models) {
    const prices = model.billing?.tokenPrices;
    if (!prices) continue;
    console.log(
        `${model.id}: input=${prices.inputPrice} output=${prices.outputPrice} ` +
            `per ${prices.batchSize} tokens (x${model.billing?.multiplier ?? 1})`,
    );
}

Python

result = await client.rpc.models.list(ModelsListRequest())

for model in result.models:
    prices = model.billing.token_prices if model.billing else None
    if prices is None:
        continue
    multiplier = model.billing.multiplier if model.billing else 1
    print(
        f"{model.id}: input={prices.input_price} output={prices.output_price} "
        f"per {prices.batch_size} tokens (x{multiplier})"
    )

list, _ := client.RPC.Models.List(ctx, &rpc.ModelsListRequest{})

for _, model := range list.Models {
    if model.Billing == nil || model.Billing.TokenPrices == nil {
        continue
    }
    prices := model.Billing.TokenPrices
    multiplier := 1.0
    if model.Billing.Multiplier != nil {
        multiplier = *model.Billing.Multiplier
    }
    in, out := 0.0, 0.0
    if prices.InputPrice != nil {
        in = *prices.InputPrice
    }
    if prices.OutputPrice != nil {
        out = *prices.OutputPrice
    }
    batch := int64(0)
    if prices.BatchSize != nil {
        batch = *prices.BatchSize
    }
    fmt.Printf("%s: input=%v output=%v per %d tokens (x%v)\n", model.ID, in, out, batch, multiplier)
}

.NET

var list = await client.Rpc.Models.ListAsync();

foreach (var model in list.Models)
{
    var prices = model.Billing?.TokenPrices;
    if (prices is null) continue;
    Console.WriteLine(
        $"{model.Id}: input={prices.InputPrice} output={prices.OutputPrice} " +
        $"per {prices.BatchSize} tokens (x{model.Billing?.Multiplier ?? 1})");
}

Java

var list = client.getRpc().models.list().join();

for (var model : list.models()) {
    var billing = model.billing();
    if (billing == null || billing.tokenPrices() == null) {
        continue;
    }
    var prices = billing.tokenPrices();
    double multiplier = billing.multiplier() != null ? billing.multiplier() : 1;
    System.out.printf("%s: input=%s output=%s per %d tokens (x%s)%n",
        model.id(), prices.inputPrice(), prices.outputPrice(), prices.batchSize(), multiplier);
}

Rust

let list = client.rpc().models().list().await?;

for model in &list.models {
    let Some(billing) = &model.billing else { continue };
    let Some(prices) = &billing.token_prices else { continue };
    let multiplier = billing.multiplier.unwrap_or(1.0);
    println!(
        "{}: input={} output={} per {} tokens (x{multiplier})",
        model.id,
        prices.input_price.unwrap_or(0.0),
        prices.output_price.unwrap_or(0.0),
        prices.batch_size.unwrap_or(0),
    );
}

Quota da conta e interações premium

account.getQuota informa a cota restante do Copilot do usuário autenticado. O mapa do quotaSnapshots resultado é chaveado por tipo de cota— geralmente premium_interactions, chate completions. Use-o para mostrar aos usuários quanto resta da cota mensal deles ou para bloquear o trabalho antes que atinjam um limite.

O exemplo usa os campos abaixo; o tipo gerado AccountQuotaSnapshot é a referência completa. As quotaSnapshots chaves são cadeias de caracteres de runtime que o sistema de tipo SDK não valida, portanto, proteja suas pesquisas.

Campo	Tipo	Description
`entitlementRequests`	`number`	Solicitações incluídas na franquia ou `-1` para ilimitado
`usedRequests`	`number`	Solicitações usadas até agora neste período
`remainingPercentage`	`number`	Porcentagem do direito restante
`resetDate`	`string`	Data em formato ISO 8601 em que a cota é redefinida

Dica

Para ler a cota de um usuário específico em vez do contexto de autenticação global da conexão (por exemplo, em um back-end multilocatário), passe o token GitHub desse usuário para getQuota. Consulte Multilocação e implantações de servidores.

Idiomas de código navigation

TypeScript

const { quotaSnapshots } = await client.rpc.account.getQuota({});
const premium = quotaSnapshots["premium_interactions"];

if (premium) {
    console.log(
        `Premium interactions: ${premium.usedRequests}/${premium.entitlementRequests} ` +
            `(${premium.remainingPercentage.toFixed(1)}% left, resets ${premium.resetDate ?? "n/a"})`,
    );
}

Python

result = await client.rpc.account.get_quota(AccountGetQuotaRequest())
premium = result.quota_snapshots.get("premium_interactions")

if premium is not None:
    print(
        f"Premium interactions: {premium.used_requests}/{premium.entitlement_requests} "
        f"({premium.remaining_percentage:.1f}% left, resets {premium.reset_date or 'n/a'})"
    )

result, _ := client.RPC.Account.GetQuota(ctx, &rpc.AccountGetQuotaRequest{})

if premium, ok := result.QuotaSnapshots["premium_interactions"]; ok {
    resets := "n/a"
    if premium.ResetDate != nil {
        resets = premium.ResetDate.Format(time.RFC3339)
    }
    fmt.Printf("Premium interactions: %d/%d (%.1f%% left, resets %s)\n",
        premium.UsedRequests, premium.EntitlementRequests, premium.RemainingPercentage, resets)
}

.NET

var result = await client.Rpc.Account.GetQuotaAsync();

if (result.QuotaSnapshots.TryGetValue("premium_interactions", out var premium))
{
    Console.WriteLine(
        $"Premium interactions: {premium.UsedRequests}/{premium.EntitlementRequests} " +
        $"({premium.RemainingPercentage:F1}% left, resets {premium.ResetDate?.ToString("o") ?? "n/a"})");
}

Java

var result = client.getRpc().account.getQuota().join();
var premium = result.quotaSnapshots().get("premium_interactions");

if (premium != null) {
    System.out.printf("Premium interactions: %d/%d (%.1f%% left, resets %s)%n",
        premium.usedRequests(), premium.entitlementRequests(),
        premium.remainingPercentage(), premium.resetDate());
}

Rust

let result = client.rpc().account().get_quota().await?;

if let Some(premium) = result.quota_snapshots.get("premium_interactions") {
    let resets = premium.reset_date.as_deref().unwrap_or("n/a");
    println!(
        "Premium interactions: {}/{} ({:.1}% left, resets {resets})",
        premium.used_requests, premium.entitlement_requests, premium.remaining_percentage,
    );
}

Escolhendo a API certa

Use este resumo para decidir qual API se encaixa em seu caso de uso:

Exiba um medidor em tempo real de custo ou tokens à medida que uma interação é executada: assine assistant.usage e session.usage_info.
Mostrar um resumo final de custo após uma interação ou sessão: chame session.usage.getMetrics.
Exiba o uso da janela de contexto ao retomar, antes de qualquer nova interação: chame session.metadata.contextInfo.
Estimar o custo antes de executar o trabalho: leia os models.list preços do token.
Avisar os usuários antes que eles esgotem seu plano: chamar account.getQuota.

Leitura adicional

Eventos de sessão de streaming: referência completa em nível de campo para assistant.usage, session.usage_info e todos os outros eventos da sessão
Observability: exportar dados de uso para OpenTelemetry para atribuição de custo
Multilocação e implantações de servidores: resolver a cota por usuário e modelos com um token GitHub

Neste artigo

Idiomas de código navigation

Idiomas de código navigation

Idiomas de código navigation

Idiomas de código navigation

Idiomas de código navigation

Idiomas de código navigation