AI Credits Specification | GitHub Agentic Workflows
Skip to main content AI Credits Specification Version : 1.5.4 Status : Draft Publication Date : 2026-11-13 Editor : GitHub Agentic Workflows Team This Version : ai-credits-specification Latest Published Version : This document Abstract Section titled “Abstract” This specification defines AI Credits (AIC) as the normative inference-cost metric for GitHub Agentic Workflows. It specifies the required calculation model from token usage and provider pricing, the canonical models.json catalog format used to store per-model pricing inputs, and the required external references for GitHub Copilot model and billing alignment.
Status of This Document Section titled “Status of This Document” This section describes the status of this document at the time of publication. This is a draft specification and may be updated, replaced, or made obsolete by other documents at any time. This document is governed by the GitHub Agentic Workflows project specifications process. Table of Contents Section titled “Table of Contents” Introduction Conformance AI Credits Accounting Model Pricing Catalog Format ( models.json ) AWF Pricing Catalog Ownership Copilot Billing Reference Requirements Reporting Requirements Compliance Testing Daily AI Credits Guardrail Per-Run AI Credits Budget Appendices References Sync Notes Change Log 1.
Introduction Section titled “1. Introduction” 1.1 Purpose Section titled “1.1 Purpose” AIC provides a single monetary-normalized metric for inference cost across supported model providers. This specification defines how conforming implementations compute AIC, how pricing data is represented, and how Copilot-specific pricing alignment is governed. 1.2 Scope Section titled “1.2 Scope” This specification covers: The normative AIC unit definition and conversion rules.
The per-invocation and aggregated AIC calculation formulas. Required models.json data structure and field semantics. Requirements for AWF-owned pricing and explicit workflow overrides. Required references to GitHub Copilot model and billing documentation. This specification does NOT cover: GitHub Actions minutes billing. Provider-side billing reconciliation and invoice dispute procedures. 1.3 Design Goals Section titled “1.3 Design Goals” The specification is designed to: Provide a testable and deterministic calculation contract.
Keep pricing inputs explicit and auditable through structured catalog files. Support model-name drift through normalized lookup and prefix fallback matching. Consume AWF pricing evidence without maintaining duplicate catalogs. 2. Conformance Section titled “2. Conformance” 2.1 Conformance Classes Section titled “2.1 Conformance Classes” Conforming implementation : Satisfies all MUST/SHALL requirements in Sections 3 through 8.
Partially conforming implementation : Computes core AIC from token usage and model pricing (Section 3) but omits one or more optional reporting requirements. 2.2 Requirements Notation Section titled “2.2 Requirements Notation” The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 .
2.3 Compliance Levels Section titled “2.3 Compliance Levels” Level 1 – Calculation : Implements AIC formulas and provider token handling (Section 3). Level 2 – Catalog : Implements required models.json structure and lookup semantics (Section 4). Level 3 – Operational : Implements AWF pricing integration, Copilot reference alignment, and reporting requirements (Sections 5–7). 3. AI Credits Accounting Model Section titled “3.
AI Credits Accounting Model” 3.1 Unit Definition Section titled “3.1 Unit Definition” A conforming implementation MUST define: 1 AIC = 0.01 USD AIC = USD / 0.01 3.2 Token Classes Section titled “3.2 Token Classes” Implementations MUST support the following token classes for cost calculation when available: Input tokens Output tokens Cache read tokens Cache write tokens Reasoning tokens 3.3 Per-Invocation Cost Formula Section titled “3.3 Per-Invocation Cost Formula” For a single invocation, implementations MUST compute USD as: cost_usd = (input_tokens × input_price_per_token) + (output_tokens × output_price_per_token) + (cache_read_tokens × cache_read_price_per_token) + (cache_write_tokens × cache_write_price_per_token) + (reasoning_tokens × reasoning_price_per_token) A conforming implementation MUST derive AIC as: aic = cost_usd / 0.01 3.4 Price Fallback Rules Section titled “3.4 Price Fallback Rules” If a model entry omits optional price fields, implementations MUST apply the following fallback behavior: cache_read_price_per_token defaults to input_price_per_token cache_write_price_per_token defaults to input_price_per_token reasoning_price_per_token defaults to output_price_per_token 3.5 Provider-Specific Input Handling Section titled “3.5 Provider-Specific Input Handling” When an invocation record provides the optional, forward-compatible input_tokens_include_cache field, implementations MUST use it instead of inferring cache semantics from the provider.
If it is true , cache-read and cache-write tokens are subsets of input_tokens and MUST be subtracted before applying the full input price. If it is false , the cache fields are additive and MUST NOT be subtracted. Legacy records without input_tokens_include_cache retain these provider defaults: Provider (normalized) Notes anthropic Direct Anthropic API openai Direct OpenAI API azure-openai / azure_openai Azure-hosted OpenAI github-copilot (and aliases github , copilot , github_models ) Treat cache-read tokens as included to preserve legacy repricing behavior when the optional field is absent.
3.6 Aggregation Section titled “3.6 Aggregation” For grouped runs (for example, episodes), implementations MUST aggregate AIC by summing per-invocation AIC values. 3.7 Entities Section titled “3.7 Entities” This subsection defines the core data entities used throughout this specification. Implementations MUST model these entities (or equivalents) when processing AIC calculation, catalog lookup, and reporting. Cross-reference: §3.3 uses InvocationRecord , §3.3 and §4 use PricingCatalogEntry , and §7 reporting consumes AICRecord .
AICRecord Section titled “AICRecord” An AICRecord represents the computed AIC result for a single workflow run or reporting period. Field Type Required Description run_id string MUST Unique identifier for the workflow run (e.g., GitHub Actions run ID). total_aic number MUST Sum of all per-invocation AIC values for the run. MUST be ≥ 0 . invocations array<InvocationRecord> MUST Ordered list of per-invocation records comprising this run’s total. computed_at string (ISO 8601) MUST UTC timestamp when this record was computed. catalog_version string SHOULD Version or content hash of the PricingCatalogEntry set used for computation.
PricingCatalogEntry Section titled “PricingCatalogEntry” A PricingCatalogEntry represents a single model’s pricing data within the models.json catalog (see §4 for catalog format). Field Type Required Description model_id string MUST Canonical model identifier (normalized; see §4.4). provider string MUST Normalized provider key (see §4.3). input number MUST Price per input token in USD. output number MUST Price per output token in USD. cache_read number SHOULD Price per cache-read token in USD.
Defaults to input when absent (§3.4). cache_write number SHOULD Price per cache-write token in USD. Defaults to input when absent (§3.4). reasoning number SHOULD Price per reasoning token in USD. Defaults to output when absent (§3.4). InvocationRecord Section titled “InvocationRecord” An InvocationRecord represents a single LLM API call and its associated token usage and cost. Field Type Required Description invocation_id string MUST Unique identifier for t
The rest of this page is on the live site.