Agent
List the caller's agents and report what they spent. Free reads; the metered call path is not here.
The Agent category is the Agent Kit's two reads: agent_list and agent_usage.
agent_list returns each agent's id, the name the owner gave it, its description,
and the MCP client id it registered with. The owner comes from the auth context,
so there is no argument that could name somebody else's agents.
id is opaque and never meaningful — quote it, do not parse it. mcpClientId is
reported for attribution and is not a unique key, because two agents on one
host may send the same clientInfo.name; key on id.
agent_usage reports what the agents spent over a window: one row per agent that
spent, most expensive first, plus the totals. Two fields deserve care:
totalCreditsis the caller's spend across every agent, so it does not change when you narrow the question.- An agent that spent nothing in the window is not a row. Its absence means zero, not missing.
A soft-deleted agent is absent from agent_list but still reports in
agent_usage under the name it had, because a charge belongs to the agent that
made it whether or not it is still registered. Refunds do not subtract from a row:
only spends count against an agent, and a refunded call that happened still counts
as a call.
Calling a tool on an agent's behalf is not here
POST /agents/{id}/call debits the owner's credits before the tool runs —
billToAgent first, so a caller who cannot afford the call gets a refusal and no
side effect — and that charge is the whole point of the Agent Kit.
Exposing it as a tool would mean one of two wrong things: a tool that spends without asking, or a tool that dispatches into the MCP server from inside an MCP server and meters the same call twice. The metering path lives where the run approval path can see it.