Metering

The metering block configures usage tracking for your topology. Monitor token consumption, cost, execution time, and agent activity to understand and optimize your multi-agent system.

Basic Syntax

metering {
  track: [tokens-in, tokens-out, cost, wall-time]
  per: agent
  output: "metrics/usage.json"
  format: json
}

Field Reference

Field	Type	Required	Description
`track`	list	Yes	Metrics to track
`per`	identifier	No	Grouping: `phase`, `agent`, or `run`
`output`	string	No	File path for metrics output
`format`	identifier	No	Output format (e.g. `json`, `csv`)
`pricing`	block	No	Custom pricing rules

Trackable Metrics

Metric	Description
`tokens-in`	Input tokens consumed
`tokens-out`	Output tokens generated
`cost`	Estimated cost in USD
`wall-time`	Elapsed wall-clock time
`agent-count`	Number of agents that ran

Grouping with `per`

The per field controls how metrics are grouped:

Value	Description
`run`	One row per topology run
`agent`	One row per agent per run
`phase`	One row per phase per run

metering {
  track: [tokens-in, tokens-out, cost]
  per: agent
  output: "metrics/per-agent.json"
  format: json
}

Custom Pricing

Override default model pricing with the pricing block:

metering {
  track: [tokens-in, tokens-out, cost]
  per: run
  output: "metrics/costs.json"
  format: json

  pricing {
    sonnet {
      input: 0.003
      output: 0.015
    }
    opus {
      input: 0.015
      output: 0.075
    }
  }
}

Output Formats

JSON

metering {
  track: [tokens-in, tokens-out, cost]
  output: "metrics/usage.json"
  format: json
}

CSV

metering {
  track: [tokens-in, tokens-out, cost, wall-time]
  output: "metrics/usage.csv"
  format: csv
}

Full Example

topology monitored-team : [pipeline] {
  agent researcher { model: sonnet  tools: [WebSearch, Read] }
  agent writer     { model: sonnet  tools: [Write] }
  agent reviewer   { model: opus    tools: [Read] }

  flow {
    researcher -> writer -> reviewer
  }

  metering {
    track: [tokens-in, tokens-out, cost, wall-time, agent-count]
    per: agent
    output: "metrics/run-report.json"
    format: json

    pricing {
      sonnet {
        input: 0.003
        output: 0.015
      }
      opus {
        input: 0.015
        output: 0.075
      }
    }
  }
}

Tips

Metering is optional but highly recommended for production topologies.
Use per: agent during development to identify which agents consume the most tokens.
Use per: run in production for high-level cost monitoring.
The output path is relative to the topology file's directory.
If pricing is not specified, AgenTopology uses built-in default pricing for known models.

Metering

On this page