Agent
Autonomous agents for your org: define them, run them, keep every run.
Also for this capability: API · CLI · MCP · SDKs
Autonomous agents for your org: define them, run them, keep every run.
| Base URL | https://api.hanzo.ai |
| Operations | 57 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Specification
Specification pending — no HIP in hanzoai/hips declares capability: agent yet. What this capability serves is below, from the API document; what it is — the store it owns, how it meters, what it publishes — is written as a HIP under HIP-0139.
Four surfaces
| Surface | Reaches this capability as | Coverage |
|---|---|---|
| REST | agent at its own prefix | 57 operations |
| CLI | hanzo agent … | 41 of 57 — the CLI pins the document on its own clock |
| SDK | AgentApi in every published client | 57 methods |
| MCP | tool agent on https://api.hanzo.ai/v1/mcp | 38 operations, 4 under the document's own id — ask describe for the rest |
Quickstart
export HANZO_API_KEY=sk-... # console.hanzo.ai → API keysThen the first call — a read that needs nothing but the key. GET /v1/agent, operation get_agent:
CLI
SDK
HTTP
MCP
hanzo agent list.ts
.py
.go
.rs
.java
import { Configuration, AgentApi } from 'hanzoai';
const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getAgent();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentApi(client).get_agent()cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.AgentAPI.GetAgent(context.Background()).Execute()
if err != nil {
return err
}use hanzo_client::apis::{configuration::Configuration, agent_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = agent_api::get_agent(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentApi;
ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));
var result = new AgentApi(client).getAgent();curl https://api.hanzo.ai/v1/agent \
-H "Authorization: Bearer $HANZO_API_KEY"MCP reaches agent through the agent tool, which names its 38 operations with its own verbs — this one among them, under a name only MCP 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_agents"
}
}
}'Answers 200 with object — ok.
Endpoints
| Endpoint | What it does |
|---|---|
POST /v1/agent/{ref}/run | Run one of your org's agents and get the recorded run back. |
GET /v1/agent/{ref}/runs | Returns one agent's execution history, newest first — each run's input, its output or its error, and how long it took. |
GET /v1/agent/{ref}/spend | Answers what one of your org's agents has spent, in integer micro-USD. |
GET /v1/agent/{ref} | Returns one agent with its system prompt and its 20 most recent runs. |
PATCH /v1/agent/{ref} | Changes an agent in place. |
DELETE /v1/agent/{ref} | Removes an agent and every run recorded against it. |
GET /v1/agent/activity | Serves the org-wide recent-activity feed. |
POST /v1/agent/ask | The MCP server a coding run's harness asks its person through. |
GET /v1/agent/builds/{org}/{project} | Returns the readable build of one product: the agent session that produced it, turn by turn — the prompts, the reasoning, the commits each turn produced — plus the exact git log that re-derives every commit binding from git itself, so nothing here has to be taken on trust. |
GET /v1/agent/builds | Returns the public index of every published build, most recently updated first, so a gallery can link straight to the story behind each product. |
DELETE /v1/agent/chat/conversations/{id}/shares/{share}/viewers/{viewer} | Remove one viewer from a link |
DELETE /v1/agent/chat/conversations/{id}/shares/{share} | Revoke a link to one of your conversations |
GET /v1/agent/chat/conversations/{id}/shares | List the live links to one of your conversations |
POST /v1/agent/chat/conversations/{id}/shares | Share one of your conversations by link |
GET /v1/agent/chat/conversations/{id} | Read one agent thread in full |
GET /v1/agent/chat/conversations | List the agent threads in your org |
POST /v1/agent/chat/conversations | Record turns in a conversation |
GET /v1/agent/chat/presets | List the agent presets available to a caller |
GET /v1/agent/chat/shared/{share} | Read a chat shared with you |
GET /v1/agent/chat/shared | List the chats shared with you |
DELETE /v1/agent/chat/shares/{share} | Revoke any link in your organization |
POST /v1/agent/chat/shares/read | Open a conversation shared by link |
GET /v1/agent/chat/shares | List every live link in your organization |
POST /v1/agent/chat | Run one tool-calling round against your org's own tools |
GET /v1/agent/coding/{session}/artifacts | Lists what a coding run left, kept after its sandbox is gone: every file it added or changed and its whole change as changes.patch, stored beside the run; the ports it served, each a preview while its sandbox is kept; its pull request and where its work was published. |
GET /v1/agent/coding/{session}/blob | Returns one file of a coding run's repository, read where the tree is read, in the shape GET /v1/git/repos/{name}/blob answers: text verbatim, anything else base64, and a file past the 1 MiB view cap marked truncated with no content. |
GET /v1/agent/coding/{session}/changes | Returns what a coding run changed, read from the forge it pushed its branch to: the commits on its branch that the base does not have, newest first; the net change of the branch against its base, one entry per file with that file's patch; and its pull request with the reviews it has had, or null while it has none. |
POST /v1/agent/coding/{session}/merge | Merges a coding run's pull request into the branch it proposes into, on the forge the run pushed to, and answers the pull request after. |
GET /v1/agent/coding/{session}/tree | Lists one directory of a coding run's repository, one level down with directories first: at the run's own branch once the forge holds it, and at the branch it started from until then — ref says which. |
POST /v1/agent/coding | Start one autonomous coding run against a repo in the caller's org |
POST /v1/agent/mcp/{server} | The MCP address a coding run's harness reaches one of its org's MCP servers through. |
GET /v1/agent/metrics | Serves the invocations-over-time histogram for the org's Agents dashboard. |
GET /v1/agent/runs | Returns the org's agent runs across EVERY agent, newest first — what ran here, for whom, on which model, how long it took, and why it failed. |
POST /v1/agent/sessions/{id}/budget | Sets, raises, or removes a session's cap. |
GET /v1/agent/sessions/{id}/control | Returns the steering commands (pause/resume/stop/message) recorded against the caller's own session that are newer than the cursor, oldest first, with the cursor to poll from next. |
POST /v1/agent/sessions/{id}/events | Records one turn of a session's transcript and answers 201 with it. |
POST /v1/agent/sessions/{id}/message | Sends a steering message to a running session — the endpoint a human or another agent interrupts through. |
POST /v1/agent/sessions/{id}/pause | Asks a running session to pause. |
GET /v1/agent/sessions/{id}/progress | Returns how far along one run is: the share of its goal that is done, whether it is running, blocked or finished, and a line saying what it is doing right now. |
POST /v1/agent/sessions/{id}/resume | Asks a paused session to continue, on the same terms as a pause. |
POST /v1/agent/sessions/{id}/stop | Ends a running session. |
GET /v1/agent/sessions/{id}/tree | Returns the subagent-flow graph rooted at this session: the session, its children, their children, each node carrying its own event count. |
GET /v1/agent/sessions/{id} | Returns one session with its direct child sessions and its 50 most recent events, oldest of those first. |
PATCH /v1/agent/sessions/{id} | Updates a session's surface-owned truth: its status, its title, the run-target it is dispatched to, and the product it built plus whether that build's story is public. |
GET /v1/agent/sessions/stream | Live session and event updates for the caller's org, as Server-Sent Events. |
GET /v1/agent/sessions | Returns the caller org's live sessions, newest first — each with its event count, its direct-child count and a one-line preview of its latest event. |
POST /v1/agent/sessions | Opens a live agent session in the caller's org — the row every surface (the CLI's outer agent, hanzo.bot, the console, chat) hangs its activity off. |
POST /v1/agent/targets/{id}/claim | The machine's long poll for work: it authenticates the daemon, stamps the liveness the dispatch gate reads (the poll IS the proof a runner is listening), and waits up to 25 seconds for the next run addressed to THIS machine. |
POST /v1/agent/targets/{id}/key | Mints (or rotates) the claim key a hanzo code --serve daemon presents to claim work for this machine, and returns it ONCE: only its SHA-256 hash is stored. |
POST /v1/agent/targets/{id}/runs/{runId}/report | Completes a claimed run: it delivers the terminal result to the run's durable owner, which is what lets that workflow finish. |
GET /v1/agent/targets/{id} | Returns one registered machine, with its live session load. |
PATCH /v1/agent/targets/{id} | Updates one machine in place. |
DELETE /v1/agent/targets/{id} | Deregisters one machine. |
GET /v1/agent/targets | Returns every machine registered to the caller's org, newest first, each with its live session load. |
POST /v1/agent/targets | Registers a machine as an agent target, or re-links one that is already registered. |
GET /v1/agent | Returns every agent defined in the caller's org, each with the number of runs recorded against it. |
POST /v1/agent | Defines an agent in the caller's org: a model, a system prompt (instructions) and a set of tool names. |
Was this page useful?