# Create agent URL: https://docs.hanzo.ai/docs/openapi/agent/post-agent > Defines an agent in the caller's org: a model, a system prompt (instructions) and a set of tool names. `POST /v1/agent` > [Agent →](https://docs.hanzo.ai/docs/openapi/agent) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/agent` | | **Method** | `POST` | | **Operation** | `post_agent` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | 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. An agent spawned by another names it as its parent; the parent must be an agent of the caller's org, and the new agent carries its whole lineage. ## Request 15 fields, body `application/json` (required). | Field | In | Type | Required | Description | | -------------------- | ---- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `avatar` | body | string | — | Avatar and Emoji are how the agent APPEARS. | | `cap_micro_usd` | body | integer (int64) | — | The budget, required. | | `computeRef` | body | string | — | ComputeRef optionally binds this bot to a visor machine. | | `description` | body | string | — | Description is the one line published as the description of the `agent_<name>` tool, which is how another agent decides whether to call this one. | | `emoji` | body | string | — | Emoji is the single glyph shown when there is no image. | | `executionMode` | body | string | — | ExecutionMode is one-shot or long-running. | | `instructions` | body | string | — | Instructions is the system prompt, up to 32 KiB, stored verbatim. | | `max_task_micro_usd` | body | integer (int64) | — | MaxTaskMicroUSD is the ceiling for a single run, in micro-USD. | | `model` | body | string | — | Model names the model to run on. | | `name` | body | string | — | Name is the agent's org-unique handle and the only required field. | | `parent` | body | string | — | Parent is the agent spawning this one — its id or name, in the caller's org. | | `period` | body | string | — | Period is the window the cap resets on: day, week or month. | | `schedule` | body | string | — | Schedule is the 5-field cron a long-running agent fires on, parsed here so a bad expression is a 400 and not an agent that silently never runs. | | `serviceAccountId` | body | string | — | ServiceAccountID optionally names the IAM agent service account (\-\) a scheduled run should be billed AS, so an autonomous run is attributable to a principal rather than only to the org. | | `tools` | body | string\[] | — | Tools are the tool names this agent may call. | ## Response | Status | Body | Meaning | | --------- | --------------- | ------- | | `201` | agent.agentView | created | | `default` | problem-details | refused | `201` body — 21 fields. | Field | In | Type | Always | Description | | -------------------- | ---- | --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | | `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). | | `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. | | `consumed_micro_usd` | body | integer (int64) | — | ConsumedMicroUSD is what has been spent in the current period, in micro-USD. | | `createdAt` | body | string | — | CreatedAt is when the agent was defined, RFC 3339 in UTC to the second. | | `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 \" when it is empty. | | `emoji` | body | string | — | Emoji is the single glyph a caller picked when they had no image. | | `executionMode` | body | string | — | ExecutionMode is one-shot or long-running, and it decides who may start this agent. | | `id` | body | string | — | ID is the agent's stable handle, minted here as "agent\_" + 32 hex characters of crypto/rand. | | `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. | | `max_task_micro_usd` | body | integer (int64) | — | MaxTaskMicroUSD is the ceiling for a single run, in micro-USD. | | `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. | | `name` | body | string | — | Name is the agent's org-unique handle, matching ^\[A-Za-z0-9]\[A-Za-z0-9.\_-]{0,63}$. | | `parent` | body | string | — | Parent is the agent that spawned this one; absent for an agent a person defined. | | `period` | body | string | — | Period is the window the cap resets on: day, week or month. | | `runs` | body | integer (int64) | — | Runs is how many executions the org has recorded against this agent, counted at read time. | | `schedule` | body | string | — | Schedule is the 5-field cron the scheduler fires a long-running agent on, evaluated once a minute. | | `serviceAccountId` | body | string | — | ServiceAccountID is the IAM agent service account (\-\) a scheduled run is billed AS. | | `status` | body | string | — | Status is the agent's readiness, and today it is "ready" on every row: an agent is a definition rather than a provisioned thing, so nothing transitions it. | | `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. | | `updatedAt` | body | string | — | UpdatedAt is the last time any field above was written, same format. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo agent create ``` **SDK** **.ts** ```ts import { Configuration, AgentApi } from 'hanzoai'; const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.postAgent({ avatar: "", cap_micro_usd: 0 }); ``` **.py** ```python 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(avatar="", cap_micro_usd=0) ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.AgentAPI.PostAgent(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust 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(&cfg, Default::default()).await?; ``` **.java** ```java 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).postAgent(); ``` **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/agent \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "avatar": "", "cap_micro_usd": 0 }' ``` **MCP** 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: ```bash 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](https://docs.hanzo.ai/docs/openapi/agent) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)