The catalog
For: tenant administrators and plugin authors.
Use the catalog to find the agents, tools, skills, flows and plugins installed for a tenant, and the nodes ready to run them. The catalog also shows the tool policy that applies to each listed function.
oz0 catalog
oz0 catalog --tenant acme --json
The catalog lists, for one tenant:
- Agents, with their task queue, the pool they share with the plugin's other agents that need the same labels, and the nodes ready to run them: nodes that run the agent's plugin and have the labels it requires.
- Tools, as
<tool>.<function>, and the nodes that have started them; and for each function, its annotations and what the tenant's tool policy does with its calls: allow, approve or refuse, and why. - Skills, with their descriptions.
- Flows, with their steps and the task queue, their plugin's pool:
pool.<plugin>, or with shared pools the pool of the plugin's node selector,pool.~<pair>. - Plugins, with where each comes from (
git,workspace,bundleoroci) and what its version is locked to: a commit, or the SHA-256 digest of a bundle or OCI artifact. The console's Agents and Tools pages show the same under each plugin's name.
Pages and search
A tenant may have thousands of agents (limits), so the catalog comes from the server a page at a time, as the other lists that grow do (lists and pages): 25 agents and flows unless page_size asks for more, at most 100, each by name, with the tenant's tools and skills whole on the first page (unless --kind asks for one kind, which is then paged too). oz0 catalog reads every page. The search runs on the server:
oz0 catalog --query invoice --kind agent
oz0 catalog --plugin billing --kind tool --json
--query keeps entries whose name, or a word of whose name or description, starts with each of its words: inv ref finds "Answers invoices and refunds", voices does not. --plugin and --kind (agent, flow, tool or skill) narrow it further. With --json the answer has totalSize, how many entries matched.
The admin API's GetCatalog and the runtime API's take page_size, page_token, query, plugin and kind, and answer next_page_token and total_size. To look one entry up, send its exact name instead of a query: a query for summarize also finds every doc-summarize-… agent, and a page of those may not hold the one you want. A page token is valid only for the tenant and the search it was made for: ask for the first page again after changing either. The runtime API's catalog has the whole catalog's hash on every page.
What tool definitions cost
Every model request of an agent carries the definitions of all the tools it may use: the name the model sees (<tool>__<function>), the description and the input schema. An agent with forty functions can spend thousands of tokens on them in every request before it says anything. The catalog shows an estimate of it: per function (tokens in --json, and on the console's Tools page) and per agent, all its tools together (the TOOL TOKENS column, toolTokens in --json, and the agent's capability card).
The figures come from the tools' listings as the first node recorded them, so a function no node has listed yet is named and left out, never guessed. They are estimates: the engine counts the text as a byte-pair tokenizer of the cl100k family would, without downloading one, and is within a few percent of such a tokenizer on our own plugins (3% on average, 14% at worst for one function). Each provider tokenizes differently and adds a tool prompt of its own, so use the numbers to compare tools and agents with each other, not to bill.
Before a plugin is installed, plugin inspect and plugin lint show the same estimate from its measured listing, and plugin lint fails when an agent's tools pass its size budget (8,000 tokens unless it sets one). For an agent that loads its tools lazily, the per-agent figure is what its requests carry, the two discovery tools and its built-ins; its card also shows what every function it lists would add.
Use it to check that an agent has somewhere to run before you start jobs for it. A job for an agent no node can run waits in its queue until one can.
An agent's name belongs to one plugin per tenant, so a job for it always means one definition. So does a tool's ID, so <tool>.<function> always means one plugin's server. A tool ID that two plugins provide, from before installs refused that, shows on both rows as a clash: no node runs it until one of the plugins goes.