Agent

Create an agent, run it, read the run back.

ref accepts the public id (agent_...) OR the org-unique name, which is why run and read can both use the name just created without waiting for an id. Names are org-unique, so an example must not hardcode one. The last step is the RUN list, not the agent read: a run is asynchronous, so the example polls it until the run it started is terminal.

CreateAgent defines an agent in the caller's org: a model, a system prompt (instructions) and a set of tool names.

POST /v1/agents · reference →

CreateAgent defines an agent in the caller's org: a model, a system prompt (instructions) and a set of tool names. The name must be unique in the org and match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. An omitted model takes the deployment's configured default; a named one is checked against the gateway's served catalog, so a model this deployment never serves is refused here rather than failing at run time. A long-running agent must carry a 5-field cron schedule (the scheduler would otherwise never fire it) and counts against a per-org cap on scheduled agents.

Parameter	In	Required
`computeRef`	body	—
`description`	body	—
`executionMode`	body	—
`instructions`	body	—
`model`	body	—
`name`	body	—
`schedule`	body	—
`serviceAccountId`	body	—
`tools`	body	—

hanzo agents create \
  --model <model> \
  --name <name>

import { Configuration, AgentsApi } from 'hanzoai';

const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.cloudPostV1Agents({ computeRef: "<computeRef>", description: "<description>" });

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).cloud_post_v1_agents(compute_ref="<computeRef>", description="<description>")

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.AgentsAPI.CloudPostV1Agents(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::cloud_post_v1_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).cloudPostV1Agents();

curl -X POST https://api.hanzo.ai/v1/agents \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "computeRef": "<computeRef>",
       "description": "<description>"
     }'

Tool post_v1_agents — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "post_v1_agents",
         "arguments": {
           "computeRef": "<computeRef>",
           "description": "<description>"
         }
       }
     }'

Run the agent.

POST /v1/agents/{ref}/run · reference →

Composes the agent's instructions with the caller input and runs a real chat completion via the in-process AI client, then records the run. A run moves money (debits the org's commerce ledger), so a validated principal is required and the org balance is pre-authorized fail-closed.

Parameter	In	Required	Description
`ref`	path	yes	The agent's public id (the `agent_...` handle) OR its org-unique name.
`input`	body	—	Caller input appended to the agent's instructions (capped at 128 KiB).

hanzo agents run <ref>

import { Configuration, AgentsApi } from 'hanzoai';

const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.cloudPostV1AgentsByRefRun({ ref: 'ref', input: "<input>" });

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).cloud_post_v1_agents_by_ref_run(ref='ref', input="<input>")

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.AgentsAPI.CloudPostV1AgentsByRefRun(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::cloud_post_v1_agents_by_ref_run(&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).cloudPostV1AgentsByRefRun();

curl -X POST https://api.hanzo.ai/v1/agents/<ref>/run \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "input": "<input>"
     }'

The MCP door does not expose this operation as a tool. It answers tools/list at https://api.hanzo.ai/v1/mcp with the ones it does.

ListAgentRuns returns one agent's execution history, newest first — each run's input, its output or its error, and how long it took.

GET /v1/agents/{ref}/runs · reference →

ListAgentRuns returns one agent's execution history, newest first — each run's input, its output or its error, and how long it took. Every row is a run that actually happened.

Parameter	In	Required	Description
`ref`	path	yes	The agent's public id (the `agent_...` handle) OR its org-unique name.
`limit`	query	—	Limit caps how many runs come back, newest first. Absent, zero or out of range (1..200) reads as 50.

hanzo agents runs <ref>

import { Configuration, AgentsApi } from 'hanzoai';

const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.cloudGetV1AgentsRefRuns({ ref: 'ref' });

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).cloud_get_v1_agents_ref_runs(ref='ref')

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.AgentsAPI.CloudGetV1AgentsRefRuns(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::cloud_get_v1_agents_ref_runs(&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).cloudGetV1AgentsRefRuns();

curl https://api.hanzo.ai/v1/agents/<ref>/runs \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool get_v1_agents_ref_runs — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "get_v1_agents_ref_runs",
         "arguments": {
           "ref": "<ref>"
         }
       }
     }'

Every command, call and tool above is generated from the same OpenAPI document that generates the SDKs themselves — the four surfaces are projections of one doc comment, so they cannot disagree.

CreateAgent defines an agent in the caller's org: a model, a system prompt (instructions) and a set of tool names.

Run the agent.

ListAgentRuns returns one agent's execution history, newest first — each run's input, its output or its error, and how long it took.

On this page