Managing Budgets with the CLI

This page covers authoring a Solace Agent Mesh budget as version-controllable YAML, called declarative config. It describes only the YAML specific to the budget kind. For more information about the sam config plan, apply, and pull workflow that applies to every kind, see Managing Configuration as Code. For more information about how budgets, the default user budget, and the budget period work, and about managing budgets from the Agent Mesh UI, see Managing Model Spend with Budgets.

Before You Start

You need a running Agent Mesh instance to apply configuration to. For more information about installing or deploying one, see Install and Deploy.

Agent Mesh checks each change that apply makes against the scopes of the token you apply with, so the token requires only the scopes for the changes in your files:

  • budget:*:read, to plan and apply any budget file.

  • budget:*:create, budget:*:update, or budget:*:delete, for the budgets that apply creates, changes, or deletes.

  • budget:*:assign, when apply changes the default user budget, deletes a budget, or assigns, moves, removes, or re-records users.

  • rbac:_:read, when a file declares users.

Only super administrators and the built-in sam_manager role hold the budget write scopes, so apply budget changes with a token that holds one of them. For more information about these scopes, see Budget and Usage Scopes.

Write the Budget

Each budget is one file in the budgets/ directory of a declarative-config repository, and the manifest lists each budget by name. The following manifest lists two budgets:

# manifest.yaml
kind: manifest
name: budgets
description: Model spend budgets.
target:
  url: http://127.0.0.1:8800
resources:
  budgets:
    - Agent Mesh
    - Sales

The following file sets the Agent Mesh budget, which covers all model spend in the deployment:

# budgets/agent-mesh.yaml
kind: budget
name: Agent Mesh
spec:
  subjectType: mesh
  amount: "5000"
  warningPercentage: 80

The following file defines a user budget and the users assigned to it:

# budgets/sales.yaml
kind: budget
name: Sales
spec:
  subjectType: user
  amount: "250"
  warningPercentage: 90
  users:
    - alice@example.com
    - system:eval
    - { type: sub, value: "00u1abcd", issuer: "https://idp.example.com" }

The following table describes the spec fields.

Field Description
subjectType Required. mesh for the Agent Mesh budget, or user for a user budget. You cannot change the budget scope after you create the budget.
amount Required. The limit in US dollars (USD) for each calendar month in Coordinated Universal Time (UTC), with at most two decimal places, such as "250" or "19.99". A user budget's limit applies to each of its users. Write amount: null for an unlimited budget.
warningPercentage Optional. The alert threshold, a whole number from 1 to 100. Omit it or write null for no alert threshold. An unlimited budget cannot set one.
isDefault Optional. Set to true to make a user budget the default user budget. On the Agent Mesh budget, isDefault: false fails the plan.
users Optional, user budgets only. The users assigned to the budget.

Omitted Fields

Apply makes the budget match its file. Every file must set amount. If you omit warningPercentage, apply removes the alert threshold. Because omitting a field clears it, the plan fails on an unknown or misspelled key in spec rather than ignoring it.

Renaming a Budget

The plan matches the Agent Mesh budget by its budget scope, not its name, so a file with a new name renames the budget in place. The plan matches a user budget by name, ignoring letter case, so a change to only the letter case also renames the budget in place. Any other new name creates a new budget, and apply deletes the old one only when you pass --prune. For more information, see The Name Is the Diff Key.

The Default User Budget

To make a user budget the default, set isDefault: true in its file. A file that omits isDefault does not change which budget is the default, so you can keep managing the default in the Agent Mesh UI. You can move the default to another budget, but you can never clear it. The plan fails if two files set isDefault: true, or if the default's file sets isDefault: false and no other file sets isDefault: true.

Assigning Users

Each entry in users takes one of the following forms:

  • An email address, as a plain string.

  • A system user, as system:<name>. You can name the built-in default, eval, and evidence system users, a system user that already exists, or a system user that the same apply creates.

  • A typed identity, { type: email|sub|system, value, issuer }. The issuer field is required for type: sub and is not allowed for the other types.

A file with users manages the budget's whole list of assignees:

  • An entry moves its user to this budget from any other budget.

  • Removing an entry deletes that assignment and returns the user to the default user budget. Apply performs the deletion only when you pass --prune.

  • A file without users leaves the budget's assignments unchanged, so you can manage them in the Agent Mesh UI.

  • A file with users: null or users: [] treats the list as empty, so with --prune, apply removes every assignee.

Agent Mesh stores an entry for someone who has not signed in yet and applies it when they first sign in.

Name each user by the identity they sign in with now. An assignment records the identity it was made by, and an assignment made in the Agent Mesh UI usually records the user's email address.

If an entry names a user who has signed in by another identity, such as a new email address or their sub, plan, apply, and pull handle the entry as follows:

  • The plan shows the recorded and the new identity on that user's entry, marked (same user).

  • Apply records the new identity whether or not you pass --prune, because recording the new identity does not delete the assignment.

  • Pull then writes the new identity.

The plan fails if the files name the same user more than once, on one budget or on different budgets, or name an unknown system user.

Deleting a Budget

When --prune deletes a budget that has assignees, Agent Mesh removes the assignments, and those users revert to the default user budget. The plan warns how many users revert, not counting any that the same apply moves to a budget that the files declare. Apply makes assignment changes before it deletes budgets. When you change a user budget's name by more than its letter case, and its file lists its users, one apply moves those users to the new budget, so they do not revert to the default user budget.

What Declarative Config Does Not Manage

Additional temporary amounts are not part of a budget file. Grant and cancel them in the Agent Mesh UI; applying a budget file leaves them unchanged. For more information, see Granting an Additional Temporary Amount.

Apply and Verify

Preview the change, then apply the manifest:

sam config plan -m manifest.yaml
sam config apply -m manifest.yaml

The plan also lists the budgets that exist in Agent Mesh but that no file declares:

  • The default user budget, initially Default User, shows as kept (tier default) with a warning, unless a file makes another budget the default. Apply never deletes the budget that stays the default. To manage it, declare it in a file.

  • Any other undeclared user budget shows as delete (needs --prune), and apply deletes it only when you pass --prune.

To confirm the apply, run sam config plan -m manifest.yaml again. The plan shows no change for each budget that a file declares, and the budgets appear on the Budgets page.

To export every budget into YAML, run sam config pull:

sam config pull --only budget --url http://127.0.0.1:8800 -o ./pulled

Pull follows these rules:

  • Pull writes every budget, including the Agent Mesh budget and Default User.

  • Pull always writes amount, and writes isDefault: true only on the default user budget.

  • Pull writes users on every budget with assignees. If it cannot write an assignee, it leaves out that budget's users and reports why.

  • Without rbac:_:read, pull writes the budgets without their users and reports that it did so.

  • If the token lacks budget:*:read, a pull without --only skips budgets and reports that it did so.

What Next?