# Update agent URL: https://docs.hanzo.ai/docs/openapi/agent/patch-agent-by-ref > Changes an agent in place. `PATCH /v1/agent/{ref}` > [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/{ref}` | | **Method** | `PATCH` | | **Operation** | `patch_agent_by_ref` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Changes an agent in place. Every field is optional; a field the request omits keeps its stored value. The resulting mode+schedule are re-validated together, so a partial update can never leave a long-running agent without the cron the scheduler needs to fire it, and a transition INTO long-running counts against the per-org cap on scheduled agents. ## Request 15 fields, body `application/json` (required). | Field | In | Type | Required | Description | | -------------------- | ---- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `ref` | path | string | yes | Ref is the agent to update — its public id or org-unique name, from the path. | | `avatar` | body | string | — | Avatar and Emoji re-draw the agent. | | `cap_micro_usd` | body | integer (int64) | — | The budget, any part of it. | | `computeRef` | body | string | — | ComputeRef re-binds (or, with "", unbinds) the visor machine. | | `description` | body | string | — | Description replaces the line other agents read in the tool catalogue. | | `emoji` | body | string | — | Emoji re-draws the agent as a glyph. | | `executionMode` | body | string | — | ExecutionMode switches between one-shot and long-running. | | `instructions` | body | string | — | Instructions replaces the system prompt whole, up to 32 KiB. | | `max_task_micro_usd` | body | integer (int64) | — | MaxTaskMicroUSD is the ceiling for a single run, in micro-USD. | | `model` | body | string | — | Model re-points the agent at another model, checked against the gateway's served catalogue exactly as create checks it. | | `period` | body | string | — | Period is the window the cap resets on: day, week or month. | | `ref` | body | string | — | Ref is the agent to update — its public id or org-unique name, from the path. | | `schedule` | body | string | — | Schedule replaces the cron. | | `serviceAccountId` | body | string | — | ServiceAccountID re-points (or, with "", clears) the IAM service account a scheduled run is billed as. | | `tools` | body | string\[] | — | Tools replaces the whole allow-list, it does not add to it. | ## Response | Status | Body | Meaning | | --------- | --------------- | ------- | | `200` | agent.agentView | ok | | `default` | problem-details | refused | `200` 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 update ``` **SDK** **.ts** ```ts import { Configuration, AgentApi } from 'hanzoai'; const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.patchAgentByRef({ ref: 'ref', 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).patch_agent_by_ref(ref='ref', 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.PatchAgentByRef(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::patch_agent_by_ref(&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).patchAgentByRef(); ``` **HTTP** ```bash curl -X PATCH 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)