IO 计量与计费

基于 Token 的输入输出计量，支持按量计费。

内置功能

IO 计量是 @multi-agent/a2a 框架的内置功能，无需手动安装或注册。只需配置 metricsProvider，框架会自动启用计费功能。

启用方式

当配置 metricsProvider 时，框架自动启用 IO 计量：

import { createAgentServer } from '@multi-agent/a2a'

const server = createAgentServer({
  agentId: 'my-agent',
  name: 'My Agent',
  version: '1.0.0',
  endpoint: { host: '0.0.0.0', port: 50061 },
  skills: [...],
  defaultSkill: 'execute',

  // 配置 metricsProvider，框架自动启用 IO 计量
  metricsProvider: {
    verifyIntegrity: async ({ agentId, sdkHash }) => {
      // 验证 SDK 完整性，返回签名密钥
      return { valid: true, signingKey: 'secret-key' }
    },

    reportMetrics: async (metrics) => {
      // 上报到计费平台
      await db.insert('io_metrics', metrics)
    },

    preCallCheck: async ({ userId, agentId }) => {
      // 检查用户余额
      const balance = await getBalance(userId)
      return { allowed: balance > 0 }
    }
  }
})

await server.start()

IOMetricsProvider 接口

interface IOMetricsProvider {
  // 必须：验证 SDK 完整性，返回签名密钥
  verifyIntegrity(params: {
    sdkVersion: string
    sdkHash: string
    agentId: string
  }): Promise<{ valid: boolean; signingKey?: string; error?: string }>

  // 必须：上报 IO 指标
  reportMetrics(metrics: VerifiedIOMetrics): Promise<void>

  // 可选：预调用检查（余额验证）
  preCallCheck?(params: {
    userId?: string
    agentId: string
    skill: string
    traceId: string
  }): Promise<{ allowed: boolean; reason?: string; code?: string }>

  // 可选：获取定价
  getPricing?(agentId: string, skill: string): Promise<AgentPricing>
}

VerifiedIOMetrics 结构

interface VerifiedIOMetrics {
  metricsId: string           // 指标 ID
  traceId: string             // 请求链 ID
  agentId: string             // Agent ID
  skill: string               // 技能名
  startedAt: string           // 开始时间（ISO 8601）
  inputCommitment: {          // 输入承诺
    commitmentId: string
    traceId: string
    contentHash: string
    tokens: number
    timestamp: number
    signature: string         // HMAC 签名
  }
  outputCommitment: {         // 输出承诺
    commitmentId: string
    traceId: string
    contentHash: string
    tokens: number
    timestamp: number
    signature: string
  }
  duration: number            // 耗时 (ms)
  userId?: string             // 计费用户
}

流程

请求 → preCallCheck → 计量输入 → Handler → 计量输出 → HMAC签名 → reportMetrics

Token 计算规则

// 中文：1 字 = 2 tokens
// 英文/数字：4 字符 = 1 token
// 空白：4 字符 = 1 token
// 符号：1 符号 = 1 token

const text = "Hello 你好"
// 'Hello ' = 6 / 4 = 2 tokens
// '你好' = 2 × 2 = 4 tokens
// 总计: 6 tokens

使用 tokenizer

import { tokenize, calculateCost } from '@multi-agent/a2a'

const tokens = tokenize('Hello 你好')  // 6
const cost = calculateCost(tokens, { pricePerToken: 0.0001 })

浏览器端计算 Token

import { tokenize, calculateCost } from '@multi-agent/a2a/browser'

const tokens = tokenize('Hello 你好')  // 6
const cost = calculateCost(tokens, { pricePerToken: 0.001 })  // 0.006

传递 userId

通过 metadata 传递计费用户：

await client.call('chat', params, {
  metadata: { 'x-user-id': userId }
})

userId 会纳入 HMAC 签名，防止伪造。

与 Tracing Plugin 的关系

特性	IO 计量	Tracing Plugin
职责	Token 计量	调用链追踪
核心数据	inputTokens, outputTokens	spanId, parentSpanId
适用场景	付费 Agent	所有 Agent

两者可同时使用：

• Tracing Plugin 负责 x-trace-id 和 x-span-id 的传播
• IO 计量专注于 Token 统计，不处理 trace 传播