Kosten zuordnen und abstimmen

Cost Attribution & Reconciliation

Every unit of resource consumption must be traceable both bottom-up (from an individual task, agent step, or API request to a tenant) and top-down (from the monthly cloud/AI provider invoice back to internal usage buckets).

Workflow

1. Multi-level attribution hierarchy:
   • Design attribution dimensions so every cost entry can be sliced along:
     • Organizational axis: tenantId -> workspaceId -> projectId -> userId / apiKeyId.
     • Execution axis: feature / workflowId -> taskId -> runId -> agentRole -> phase -> toolCallId.
     • Infrastructure axis: provider -> service -> modelOrSku -> environment (prod, staging, ci).
   • Preserve both the initiating actor (user who triggered the work) and the executing actor (subagent or worker that incurred the cost).
2. Explicitly classify unattributed and platform-internal usage:
   • Never drop events without a customer tenantId. Route them to explicit internal cost centers (system:healthcheck, system:eval_suite, system:embeddings_backfill, system:unattributed_quarantine).
   • Track the attribution coverage ratio: $\text{Attributed Cost} / \text{Total Internal Ledger Cost}$ (target $\ge 99%$).
3. Reconcile internal ledger against provider billing APIs / exports:
   • Ingest external usage/cost reports (OpenAI/Anthropic usage & cost APIs, cloud billing / FOCUS exports, storage metrics) segmented by provider key, workspace, project, or billing tag.
   • Compare for each (date, provider, modelOrSku) bucket: $$\Delta_{\text{units}} = \text{ProviderUnits} - \text{InternalUnits}, \quad \Delta_{\text{cost}} = \text{ProviderCost} - \text{InternalCost}$$
   • Classify discrepancies systematically:
     • Missing instrumentation: Endpoints, retries, or subagent calls bypassing the metering hook.
     • Clock / timezone skew: Events near UTC midnight bucketed into adjacent days.
     • Estimated vs. actual gap: Aborted streams or tokenizer estimates diverging from provider counts.
     • Rate card mismatch: Discount tiers, cache multipliers, or minimum fees missing from the catalog.

Anti-Patterns to Avoid

• Lumping all API calls under one shared key with no metadata: Prevents verifying which environment or tenant caused an invoice spike.
• Silently smearing reconciliation errors across customers: Keep invoice variance in a dedicated reconciliation_variance bucket until root-caused.
• Confusing internal cost attribution with customer invoicing: Keep internal COGS tracking and external customer plan billing cleanly separated.