For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Carry a validated caller identity into AWS and Google Cloud billing records, so LLM spend is attributed per team, app, user, or any chosen attribution value on the provider’s own bill.

Invoice-grade attribution means that the value that names a request reaches the cloud provider’s own billing records. Finance then slices the same numbers that the provider charges. Agentgateway can also compute per-team spend from token counts and a price list, but that number is an estimate rather than the invoice. For the reasoning behind the term, see Invoice-grade attribution on Amazon Bedrock with agentgateway.

You configure the attribution values, and agentgateway resolves each one from an identity that it validated or from a static value that you assign.

Before you begin

1. Set up an agentgateway proxy.
2. Create the AgentgatewayBackend and HTTPRoute for the LLM provider that you want to attribute, such as Amazon Bedrock.
3. Apply a JWT authentication policy to the route, so that jwt.* values are available to attribution expressions.

Amazon Bedrock

Bedrock attributes inference cost to the IAM principal that made the call. For gateway traffic, the documented pattern is a per-caller session. Agentgateway assumes an AWS Identity and Access Management (IAM) role for each request. The session name and the session tags come from the caller’s identity.

The session name lands in AWS CloudTrail and in the IAM principal column of the Cost and Usage Report. The tags surface as cost allocation tags in Cost Explorer and in the Cost and Usage Report.

Session identity and tags

Configure assumeRole in the auth.aws settings of the AgentgatewayBackend. The session name is either a static sessionName or a sessionNameExpression. Each tag is either a static value or a CEL expression that agentgateway evaluates against the request.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayBackend
metadata:
  name: bedrock
  namespace: agentgateway-system
spec:
  ai:
    provider:
      bedrock:
        model: "amazon.nova-micro-v1:0"
        region: "us-east-1"
  policies:
    auth:
      aws:
        assumeRole:
          roleArn: arn:aws:iam::123456789012:role/bedrock-invoke
          sessionNameExpression: jwt.sub
          tags:
          - key: user
            expression: jwt.sub
          - key: team
            expression: request.headers["x-team"]
          - key: environment
            value: prod
EOF

Review the following table to understand this configuration. For more information, see the API reference.

Agentgateway checks static values against the STS limits when the resource is accepted. Expressions are evaluated per request and fail closed. An expression that errors, or that produces an empty or invalid value, rejects the request before agentgateway calls AWS. No request reaches Bedrock unattributed.

To see the tags on the bill, activate the keys as cost allocation tags in the AWS Billing console. New keys take up to 24 hours to become available for activation. Activated tags apply to usage from that point on.

Per-request metadata

Bedrock also accepts per-call request metadata, which it records in the model invocation logs rather than on the bill. Session tags are bound per session and surface only as aggregated billing data. Request metadata is recorded per call, so it is where per-prompt attribution lives. You can query it in CloudWatch Logs Insights or Amazon Athena.

Bedrock does not require request metadata. A request that omits it still succeeds, and Bedrock records whatever the caller sends. Setting the metadata at the gateway is what makes it mandatory.

Set the metadata with a finalTransformations entry in an AgentgatewayPolicy that targets the route. Agentgateway applies a final transformation after it converts the request to the provider format. On the Converse API that Bedrock chat routes use, the field is requestMetadata.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: bedrock-request-metadata
  namespace: agentgateway-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: bedrock
  backend:
    ai:
      finalTransformations:
      - field: requestMetadata
        expression: |
          coalesce(
            llmRequest.requestMetadata.merge({"user": jwt.sub, "team": request.headers["x-team"]}),
            {"user": jwt.sub, "team": request.headers["x-team"]}
          )
EOF

Callers can send their own metadata in the x-bedrock-metadata header, so two postures are available:

• Merge, as in the previous example. Your keys win on conflict, and caller keys that you did not claim survive. The coalesce call is required, because .merge errors when the caller sent no metadata and the field is absent from the converted request. The coalesce call then falls through to the literal.
• Replace. Your values are the only ones that reach Bedrock, and any caller metadata is dropped. Use an expression of {"user": jwt.sub, "team": request.headers["x-team"]} instead of the coalesce call.

Bedrock records request metadata only when model invocation logging is enabled in the region. Bedrock allows at most 16 entries, with keys and values up to 256 characters in a restricted character set. Bedrock rejects values outside those limits at request time.

A final transformation sets fields on the converted request body, which covers the Converse API that chat routes use. The InvokeModel family, such as embeddings and passthrough, takes metadata as a signed header instead, which this transformation does not set.

Google Vertex AI

On Vertex AI, agentgateway sets billing labels on the native generateContent request, and those labels reach the Google Cloud billing export. Without a transformation, the labels on the request are whatever the caller sent. The transformation is what makes them yours.

Create the AgentgatewayBackend and HTTPRoute for Google Vertex AI first. Then configure the labels with a finalTransformations entry in an AgentgatewayPolicy that targets the Vertex AI route. The same merge and replace postures apply, because callers can send their own labels.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: vertex-labels
  namespace: agentgateway-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: vertex
  backend:
    ai:
      finalTransformations:
      - field: labels
        expression: |
          coalesce(
            llmRequest.labels.merge({"tenant": jwt.sub, "cost_center": "platform"}),
            {"tenant": jwt.sub, "cost_center": "platform"}
          )
EOF

To replace caller labels instead of merging them, use an expression of {"tenant": jwt.sub, "cost_center": "platform"}.

Google allows up to 64 labels per request, with keys and values up to 63 characters from a restricted character set. Vertex AI rejects values outside those limits at request time. Billing export rows carry the labels next to the cost. You can group the export by labels.tenant or by any other key that you set.

Choose attribution values

Where the value comes from decides what the bill is worth in a dispute.

• jwt.* values come from a token that agentgateway validated under a JWT authentication policy. The value is a fact about who logged in, checked on every request.
• Static values are the ones that you assign to the backend or route. Use them for callers that do not log in, such as batch jobs and internal services.
• request.headers[...] is the caller’s word. Use it only for dimensions that the caller is trusted to assert, such as an environment name. Never use it for the identity that chargeback depends on.

Keep the values low-cardinality on the bill. Every distinct set of session tags is its own STS session and its own set of line items in the Cost and Usage Report. Tag by team and cost center everywhere, and tag per user only where the chargeback question needs it.

Per-prompt detail belongs in request metadata and the invocation logs, not in session tags.

Verify

Learn more

• Transform requests for request transformations and the CEL context.
• Virtual keys to attribute usage inside agentgateway.
• Amazon Bedrock provider configuration.