Create 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.

POST /v1/agent/roster

Agent → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/agent/roster`
Method	`POST`
Operation	`post_agent_roster`
Auth	`Authorization: Bearer $HANZO_API_KEY`

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. Applying the same roster again (or resuming an interrupted launch) updates existing roles in place without duplicating agents or budgets.

Request

20 fields, body application/json (required).

Field	In	Type	Required	Description
`roles`	body	agent.RoleSpec[]	—	Roles are the explicit role definitions to create or update in topological manager order.
`roles[].cap_micro_usd`	body	integer (int64)	—	CapMicroUSD is the period budget cap in integer micro-USD; defaults to the template's cap when omitted.
`roles[].duties`	body	string	—	Duties is the system prompt (instructions) governing the role's behavior and output.
`roles[].executionMode`	body	string	—	ExecutionMode is "one-shot" (default) or "long-running".
`roles[].expertise`	body	string	—	Expertise is the catalog description explaining the role's domain expertise.
`roles[].function`	body	string	—	Function names the studio function ("lead" or one of the seven studio functions).
`roles[].manager`	body	string	—	Manager names the parent agent handle or id this role reports to in the org chart.
`roles[].max_task_micro_usd`	body	integer (int64)	—	MaxTaskMicroUSD is the per-run budget ceiling in integer micro-USD; defaults to the template's ceiling when omitted.
`roles[].model`	body	string	—	Model optionally overrides the model this role runs on.
`roles[].name`	body	string	—	Name is the agent handle to create or update in the organization (e.g. "venture-lead" or "specialist-regulatory-clinical").
`roles[].output`	body	string	—	Output describes the required deliverable format for this role.
`roles[].period`	body	string	—	Period is the budget reset window (day, week, or month); defaults to "month".
`roles[].schedule`	body	string	—	Schedule is the 5-field cron expression when executionMode is "long-running".
`roles[].sources`	body	string[]	—	Sources lists the knowledge and evidence sources this role is permitted to query.
`roles[].templateId`	body	string	—	TemplateID optionally selects a shared RoleTemplate by id to inherit defaults from.
`roles[].templateVersion`	body	string	—	TemplateVersion records the explicit shared template version used for this role; defaults to StudioTemplateVersion.
`roles[].tools`	body	string[]	—	Tools lists the MCP tool names this role is allowed to call.
`seedDefaultSeven`	body	boolean	—	SeedDefaultSeven, when true, seeds the default venture-lead and all seven studio function specialists before applying any custom roles in Roles.
`templateVersion`	body	string	—	TemplateVersion is the shared role template version to stamp on enrolled roles; defaults to StudioTemplateVersion.
`venture`	body	string	—	Venture is the venture slug this roster belongs to, used for attribution and metadata.

Response

Status	Body	Meaning
`200`	agent.applyRosterOut	ok
`default`	problem-details	refused

200 body — 28 fields.

Field	In	Type	Always	Description
`agents`	body	agent.agentView[]	—	Agents are the enrolled agent views in the organization after applying the roster.
`agents[].avatar`	body	string	—	Avatar is an image the agent is drawn as — a link to one, or the bytes inline as a data URL, up to 96 KiB.
`agents[].avatar_licence`	body	string	—	AvatarLicence is the short name of the licence the avatar image is used under ("Public domain", "CC0").
`agents[].avatar_source`	body	string	—	AvatarSource is the page the avatar image is described on, where its author and licence can be read (a Wikimedia Commons file page, say).
`agents[].cap_micro_usd`	body	integer (int64)	—	CapMicroUSD is the total this agent may spend within one Period, as an integer number of micro-USD (1,000,000 = $1).
`agents[].computeRef`	body	string	—	ComputeRef is the visor machine this bot is bound to, opaque here: this package stores and echoes it, and the binding's lifecycle belongs elsewhere.
`agents[].consumed_micro_usd`	body	integer (int64)	—	ConsumedMicroUSD is what has been spent in the current period, in micro-USD.
`agents[].createdAt`	body	string	—	CreatedAt is when the agent was defined, RFC 3339 in UTC to the second.
`agents[].description`	body	string	—	Description is the one line another agent reads when deciding whether to call this one: the tool catalogue publishes it as the description of `agent_<name>`, falling back to "agent <name>" when it is empty.
`agents[].emoji`	body	string	—	Emoji is the single glyph a caller picked when they had no image.
`agents[].executionMode`	body	string	—	ExecutionMode is one-shot or long-running, and it decides who may start this agent.
`agents[].id`	body	string	—	ID is the agent's stable handle, minted here as "agent_" + 32 hex characters of crypto/rand.
`agents[].lineage`	body	string[]	—	Lineage is every agent above this one, nearest first — the parent, its parent, and so on to the agent a person defined.
`agents[].max_task_micro_usd`	body	integer (int64)	—	MaxTaskMicroUSD is the ceiling for a single run, in micro-USD.
`agents[].model`	body	string	—	Model is the Zen model this agent runs on, and it is always OUR name for it: writes normalize through cloud.ZenModel and the read normalizes again, so an upstream family name never leaves here even from a row written before that rule existed.
`agents[].name`	body	string	—	Name is the agent's org-unique handle, matching ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.
`agents[].parent`	body	string	—	Parent is the agent that spawned this one; absent for an agent a person defined.
`agents[].period`	body	string	—	Period is the window the cap resets on: day, week or month.
`agents[].runs`	body	integer (int64)	—	Runs is how many executions the org has recorded against this agent, counted at read time.
`agents[].schedule`	body	string	—	Schedule is the 5-field cron the scheduler fires a long-running agent on, evaluated once a minute.
`agents[].serviceAccountId`	body	string	—	ServiceAccountID is the IAM agent service account (<org>-<agent>) a scheduled run is billed AS.
`agents[].status`	body	string	—	Status is the agent's readiness: "ready", or "retired" for a built-in whose member has left Hanzo's team.
`agents[].tools`	body	string[]	—	Tools are the tool names this agent may call, and the list IS the authority: an agent that declares none gets none.
`agents[].updatedAt`	body	string	—	UpdatedAt is the last time any field above was written, same format.
`created`	body	integer (int64)	—	Created is how many new agent roles were created by this call.
`templateVersion`	body	string	—	TemplateVersion is the shared template version applied.
`updated`	body	integer (int64)	—	Updated is how many existing agent roles were updated idempotently in place without duplicating agents or budgets.
`venture`	body	string	—	Venture is the venture slug the roster was applied for.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo agent roster create

.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.postAgentRoster({ roles: [{"cap_micro_usd":0,"duties":"<duties>","executionMode":"<executionMode>","expertise":"<expertise>"}], seedDefaultSeven: false });

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).post_agent_roster(roles=[{"cap_micro_usd":0,"duties":"<duties>","executionMode":"<executionMode>","expertise":"<expertise>"}], seed_default_seven=False)

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

resp, _, err := client.AgentAPI.PostAgentRoster(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::post_agent_roster(&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).postAgentRoster();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X POST https://api.hanzo.ai/v1/agent/roster \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "roles": [
         {
           "cap_micro_usd": 0,
           "duties": "<duties>",
           "executionMode": "<executionMode>",
           "expertise": "<expertise>"
         }
       ],
       "seedDefaultSeven": false
     }'

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"
         }
       }
     }'

Agent API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousCreate review NextCreate budget