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
Operations73
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 prefix73 operations
CLIhanzo agent …73 of 73
SDKAgentApi in every published client73 methods
MCPtool agent on https://api.hanzo.ai/v1/mcp51 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 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

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 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}/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 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/a2aTalk to the Hanzo assistant over A2A (Agent2Agent 1.0, JSON-RPC).
GET /v1/agent/activityServes the recent-activity feed.
POST /v1/agent/askThe MCP server a coding run's harness asks its person through.
POST /v1/agent/briefs/{id}/rerunRe-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/briefsReturns every durable research brief recorded in the caller's organization, newest first.
POST /v1/agent/briefsAssigns 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/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
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/conversationsList your own conversations
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}/extendGives your running coding run more time.
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.
POST /v1/agent/coding/{session}/pullOpens 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}/steerRedirect your running or paused coding session.
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 Agents dashboard, over the caller's own runs.
POST /v1/agent/proposals/{id}/decideApproves or rejects a proposed role candidate.
POST /v1/agent/proposals/reviewRuns 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/proposalsReturns the organization's nightly role candidate proposals, optionally filtered by venture slug or decision status.
GET /v1/agent/roster/templatesReturns the seven canonical studio functions and the shared, versioned role templates that ventures reuse.
POST /v1/agent/rosterTurns 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/runsReturns 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}/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.
GET /v1/agent/sessions/{id}/eventsReads 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}/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?
Broken link or missing step? Drop it in #docs on Discord or open a PR.