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 URLhttps://api.hanzo.ai
Operations57
AuthAuthorization: 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

SurfaceReaches this capability asCoverage
RESTagent at its own prefix57 operations
CLIhanzo agent …41 of 57 — the CLI pins the document on its own clock
SDKAgentApi in every published client57 methods
MCPtool agent on https://api.hanzo.ai/v1/mcp38 operations, 4 under the document's own id — ask describe for the rest

Quickstart

export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/agent, operation get_agent:

hanzo agent list
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

EndpointWhat it does
POST /v1/agent/{ref}/runRun one of your org's agents and get the recorded run back.
GET /v1/agent/{ref}/runsReturns 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}/spendAnswers 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/activityServes the org-wide recent-activity feed.
POST /v1/agent/askThe 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/buildsReturns 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}/sharesList the live links to one of your conversations
POST /v1/agent/chat/conversations/{id}/sharesShare one of your conversations by link
GET /v1/agent/chat/conversations/{id}Read one agent thread in full
GET /v1/agent/chat/conversationsList the agent threads in your org
POST /v1/agent/chat/conversationsRecord turns in a conversation
GET /v1/agent/chat/presetsList the agent presets available to a caller
GET /v1/agent/chat/shared/{share}Read a chat shared with you
GET /v1/agent/chat/sharedList the chats shared with you
DELETE /v1/agent/chat/shares/{share}Revoke any link in your organization
POST /v1/agent/chat/shares/readOpen a conversation shared by link
GET /v1/agent/chat/sharesList every live link in your organization
POST /v1/agent/chatRun one tool-calling round against your org's own tools
GET /v1/agent/coding/{session}/artifactsLists 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}/blobReturns 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}/changesReturns 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}/mergeMerges 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}/treeLists 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/codingStart 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/metricsServes the invocations-over-time histogram for the org's Agents dashboard.
GET /v1/agent/runsReturns 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}/budgetSets, raises, or removes a session's cap.
GET /v1/agent/sessions/{id}/controlReturns 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}/eventsRecords one turn of a session's transcript and answers 201 with it.
POST /v1/agent/sessions/{id}/messageSends a steering message to a running session — the endpoint a human or another agent interrupts through.
POST /v1/agent/sessions/{id}/pauseAsks a running session to pause.
GET /v1/agent/sessions/{id}/progressReturns 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}/resumeAsks a paused session to continue, on the same terms as a pause.
POST /v1/agent/sessions/{id}/stopEnds a running session.
GET /v1/agent/sessions/{id}/treeReturns 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/streamLive session and event updates for the caller's org, as Server-Sent Events.
GET /v1/agent/sessionsReturns 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/sessionsOpens 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}/claimThe 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}/keyMints (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}/reportCompletes 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/targetsReturns every machine registered to the caller's org, newest first, each with its live session load.
POST /v1/agent/targetsRegisters a machine as an agent target, or re-links one that is already registered.
GET /v1/agentReturns every agent defined in the caller's org, each with the number of runs recorded against it.
POST /v1/agentDefines an agent in the caller's org: a model, a system prompt (instructions) and a set of tool names.

All Hanzo APIs · Interactive reference

Was this page useful?