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 | 73 |
| 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 | 73 operations |
| CLI | hanzo agent … | 73 of 73 |
| SDK | AgentApi in every published client | 73 methods |
| MCP | tool agent on https://api.hanzo.ai/v1/mcp | 51 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 51 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 the caller's own runs of one agent, 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 the caller's own 20 most recent runs of it: a run's input and output are its person's. |
PATCH /v1/agent/{ref} | Changes an agent in place. |
DELETE /v1/agent/{ref} | Removes an agent and every run recorded against it. |
POST /v1/agent/a2a | Talk to the Hanzo assistant over A2A (Agent2Agent 1.0, JSON-RPC). |
GET /v1/agent/activity | Serves the recent-activity feed. |
POST /v1/agent/ask | The MCP server a coding run's harness asks its person through. |
POST /v1/agent/briefs/{id}/rerun | Re-executes only the failed or pending specialist child tasks on a brief without re-running or duplicating specialists that already succeeded, then runs the lead synthesis once all specialist tasks are complete. |
GET /v1/agent/briefs/{id} | Returns one durable research brief and all of its specialist child tasks, citations, unsupported claims, open questions, and attribution records. |
GET /v1/agent/briefs | Returns every durable research brief recorded in the caller's organization, newest first. |
POST /v1/agent/briefs | Assigns a research brief to a venture lead, dispatches durable child tasks to the designated specialist agents, attributes each specialist's cited findings and unsupported-claim flags, and runs the lead synthesis once all specialist tasks complete. |
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 |
PATCH /v1/agent/chat/conversations/{id} | Rename, pin or archive one of your conversations |
DELETE /v1/agent/chat/conversations/{id} | Delete one of your conversations |
GET /v1/agent/chat/conversations | List your own conversations |
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}/extend | Gives your running coding run more time. |
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. |
POST /v1/agent/coding/{session}/pull | Opens the pull request for the branch a coding run pushed, as the run's person and with no agent run, and answers its number and address. |
POST /v1/agent/coding/{session}/steer | Redirect your running or paused coding session. |
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 Agents dashboard, over the caller's own runs. |
POST /v1/agent/proposals/{id}/decide | Approves or rejects a proposed role candidate. |
POST /v1/agent/proposals/review | Runs the scheduled review of repeated failures, missing expertise, and human review effort across the organization's runs, briefs, and observed coverage gaps, producing role candidate proposals with concrete examples, a micro-USD cost estimate, and a reporting line. |
GET /v1/agent/proposals | Returns the organization's nightly role candidate proposals, optionally filtered by venture slug or decision status. |
GET /v1/agent/roster/templates | Returns the seven canonical studio functions and the shared, versioned role templates that ventures reuse. |
POST /v1/agent/roster | Turns an approved organization chart into agent definitions in the caller's organization, resolving manager reporting lines (parent and lineage) and shared role templates with explicit versions. |
GET /v1/agent/runs | Returns the caller's own agent runs across EVERY agent of the org, newest first — what ran, 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. |
GET /v1/agent/sessions/{id}/events | Reads a session's log in order, a page at a time: everything after the seq a reader last saw, so a poll resumes exactly where it stopped. |
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?
Broken link or missing step? Drop it in #docs on Discord or open a PR.