Agent FinOps

/agent-finops tracks agent runs, priced tool calls, model/provider cost, and infrastructure cost.

Open the page and understand scope

Select Agent FinOps in the main sidebar or open /agent-finops. Any signed-in user can open it.

• Platform admins (ADMIN, ADMIN_VIEWER) see every agent. Other users see agents they own or that belong to one of their teams or organizations. When an organization is selected in the header organization switcher, only its agents are shown.
• Viewer roles (ADMIN_VIEWER, USER_VIEWER) are read-only.
• Users with write access can register agents within their own attribution scope and become the owner. The agent owner, an admin of the agent's team or organization, and ADMIN users can update, pause or delete the agent and ingest or complete its runs and tool calls.
• Only ADMIN users can register, enable, disable or delete priced tools and see the Tool catalog.

See Roles.

Filter the view

The toolbar applies to the whole page:

• Period — Last 7 days, Last 30 days (default) or Last 90 days.
• Environment, Team and Status (Active, Paused, Archived).
• Search — matches agent names, descriptions and IDs, and filters the tool catalog by tool name, provider or ID.

Clear all resets environment, team, status and search. The filters are kept in the URL (?days=&environment=&teamId=&status=&q=), so a filtered view can be shared. Totals, rankings and the agent list follow the filters; pending approvals and the Tools count do not.

Read the dashboard

• Agents, Recent runs, Tools and Recent run cost cards show visible agents, runs in the period, active priced tools and the period's total run cost with the number of pending approvals. The counts and cost cover every visible run in the period, not only the listed rows.
• Run cost composition splits the period's run cost into model/provider, tools and infrastructure.
• Most expensive agents, Most expensive tools and Most expensive runs rank the period. Tools show usage in their pricing unit or as a call count; runs show their model, tool and infrastructure cost.
• Budget visibility shows active budgets with spend against the limit and an On track, Near limit (80% or more) or Over budget status. Platform admins see the budgets with the highest spend; other users see budgets for themselves, their teams and organizations, and the listed agents with their applications, cost centers and tools. Budgets opens Budgets.
• Pending cost approvals shows pending high-cost agent and budget increase requests with the total requested amount. Platform admins see all of them; other users see their own requests and those they can review. Each item opens Approvals (/admin/requests).
• Agents and recent runs shows each agent's organization, team, application, cost center and environment, and the cost of its latest runs. Hover a run to see its tool call costs.
• Analyze agent token efficiency in Tokenomics opens Tokenomics to investigate calls per run, long histories and tool-result overhead.

Register agents and tools

Users with write access use the Manage row: Register agent, Register priced tool (ADMIN only), Ingest agent run (when an agent is listed) and Ingest tool call (when a run in the period and an active tool are listed). One form is open at a time.

Register an agent with a name and optional stable ID, organization, team, application, cost center, environment, and description. Register a tool with a name and optional stable ID, provider, pricing unit and unit cost; the currency is USD. In the Tool catalog, tools can be enabled, disabled, or deleted.

In Agents and recent runs, Pause and Activate change an agent's status. An agent with runs cannot be deleted; archive it instead by setting its status to ARCHIVED through the API.

Stable IDs make repeated control-plane ingestion idempotent. Do not put prompts, credentials, or customer payloads in metadata.

Ingest costs

An agent run records provider and infrastructure cost. A run inherits missing scope values from its registered agent, and supplied values cannot conflict with the agent's fixed attribution. Gateway-ingested run attribution and costs are immutable; only their status can be completed. Complete marks a running run as succeeded. Only portal-ingested runs can be deleted.

Tool calls belong to a run. Enter a quantity and either an explicit cost or let the active tool unit price calculate it. Adding a tool call recalculates the run's tool and total cost.

Use Cost events to inspect the resulting event-level attribution and Tokenomics platform recommendations for generated agent recommendations.

API

The page reads GET /api/control-plane/agent-finops with the signed-in portal session. Optional query parameters:

Parameter	Values
days	7, 30 or 90 (default 30)
environment	DEVELOPMENT, STAGING or PRODUCTION
teamId	Team ID
status	ACTIVE, PAUSED or ARCHIVED
q	Search text (agent name, description or ID; up to 100 characters)
limit	Agents and tools to list, 1–250 (default 100)

An out-of-range limit is clamped; other invalid values are ignored. The response includes totals (agents, runs, providerCost, toolCost, infrastructureCost, totalCost) across all matching agents and their runs in the period, the applied filters, and a name on each ranked agent and tool.

The benefit is a single accountable total for workflows that combine model, tool, and infrastructure spend instead of reporting model calls alone. See FinOps relationship and data flow.