OpenapiAgents
Returns every agent defined in the caller's org, each with the number of runs…
Returns every agent defined in the caller's org, each with the number of runs recorded against it.
GET /v1/agents
| Address | https://api.hanzo.ai/v1/agents |
| Method | GET |
| Operation | get_agents |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Returns every agent defined in the caller's org, each with the number of runs recorded against it.
Request
GET /v1/agents takes no parameters and no body — the credential is the whole request.
Response
| Status | Body | Meaning |
|---|---|---|
200 | agentList | ok |
200 body — 14 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
agents | body | agentView[] | — | Agents is the org's agents, each carrying its recorded run count. |
agents[].computeRef | body | string | — | ComputeRef is the visor machine this bot is bound to, opaque here: this package stores and echoes it, and the binding's lifecycle belongs elsewhere. |
agents[].createdAt | body | string | — | CreatedAt is when the agent was defined, RFC 3339 in UTC to the second. |
agents[].description | body | string | — | Description is the one line another agent reads when deciding whether to call this one: the tool catalogue publishes it as the description of agent_<name>,… |
agents[].executionMode | body | string | — | ExecutionMode is one-shot or long-running, and it decides who may start this agent. |
agents[].id | body | string | — | ID is the agent's stable handle, minted here as "agent_" + 32 hex characters of crypto/rand. |
agents[].model | body | string | — | Model is the Zen model this agent runs on, and it is always OUR name for it: writes normalize through cloud.ZenModel and the read normalizes again, so an… |
agents[].name | body | string | — | Name is the agent's org-unique handle, matching ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. |
agents[].runs | body | integer | — | Runs is how many executions the org has recorded against this agent, counted at read time. |
agents[].schedule | body | string | — | Schedule is the 5-field cron the scheduler fires a long-running agent on, evaluated once a minute. |
agents[].serviceAccountId | body | string | — | ServiceAccountID is the IAM agent service account (<org>-<agent>) a scheduled run is billed AS. |
agents[].status | body | string | — | Status is the agent's readiness, and today it is "ready" on every row: an agent is a definition rather than a provisioned thing, so nothing transitions it. |
agents[].tools | body | string[] | — | Tools are the tool names this agent may call, and the list IS the authority: an agent that declares none gets none. |
agents[].updatedAt | body | string | — | UpdatedAt is the last time any field above was written, same format. |
Failure carries the platform error shape — see Errors.
Examples
hanzo agents listimport { Configuration, AgentsApi } from 'hanzoai';
const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getAgents();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentsApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentsApi(client).get_agents()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.AgentsAPI.GetAgents(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, agents_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = agents_api::get_agents(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentsApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new AgentsApi(client).getAgents();curl https://api.hanzo.ai/v1/agents \
-H "Authorization: Bearer $HANZO_API_KEY"The door reaches agents through the agents tool, which names its 36 operations with its own verbs — this one among them, under a name only the door declares. describe explains any of them:
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "describe",
"arguments": {
"op": "list_agent_conversations"
}
}
}'How is this guide?