Patch an agent

Patch some fields of an agent and keep the rest.

PATCH /api/v2/agents/{agent_name}

Python

from hai_agents import Client

client = Client()

agent = client.agents.patch_agent(
    agent_name="my-research-bot",
    instructions="Always cite the page you took each claim from.",
)
print(agent.instructions)

Behavior

Each patch is saved as a new revision. Send null to clear an optional field. description and environments can’t be null. The merged result is validated like a full update.

Headers

If-Match · string

The ETag of the revision you based this change on, for example "3". If the agent has moved past it, the write fails with 412. Omit it, or send *, to apply your fields to whatever is current.

Path parameters

agent_name · string · required

The agent’s name, for example my-research-bot or myorg/web-helper.

Query parameters

message · string

A note stored on the new revision, such as why you made the change. Up to 500 characters. Shown by List revisions.

Request body

Any subset of these agent fields: description, environments, model, reasoning_effort, instructions, subagents, skills, answer_format, tools. name can’t change.

Response

200 with the updated agent object, with its new revision in the ETag header.

Python

from hai_agents import Client

client = Client()

agent = client.agents.patch_agent(
    agent_name="my-research-bot",
    instructions="Always cite the page you took each claim from.",
)
print(agent.instructions)

Errors

Status	Cause
400	If-Match is not a single revision tag.
403	The agent is reserved (h/) and read-only.
404	Not found, or not in your organization. Also sent when a skill, environment, or subagent it references is missing.
409	Without If-Match, the agent kept changing while the patch was merged. Retry.
412	If-Match names a revision that isn’t the current one. The ETag header has the current one: read it, reapply your change, and retry.
422	The merged spec fails validation, for example environments emptied on an agent with no subagents or tools, or null for description or environments.