Update an agent

Update an agent by replacing its whole configuration.

PUT /api/v2/agents/{agent_name}

Python

from hai_agents import Client

client = Client()

agent = client.agents.update_agent(
    agent_name="my-research-bot",
    name="my-research-bot",
    description="Researches a topic and returns a sourced summary.",
    environments=["h/browser"],
    instructions="Always cite the page you took each claim from.",
    skills=["web-browse", "extract-data"],
)
print(agent.name)

200

{
  "name": "my-research-bot",
  "description": "Researches a topic and returns a sourced summary.",
  "environments": ["h/browser"],
  "model": null,
  "reasoning_effort": null,
  "instructions": "Always cite the page you took each claim from.",
  "subagents": null,
  "skills": ["web-browse", "extract-data"],
  "answer_format": null,
  "tools": null
}

Behavior

Each update is saved as a new revision. Sessions pinned to an earlier revision with name:N keep running that one. Sending the current spec changes nothing. The name can’t change. To change a few fields, patch the agent.

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 write regardless.

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

The full agent, with the same fields and rules as Create an agent. The name must equal the URL identifier. Omitted fields reset to their defaults: leaving out instructions, model, skills, or answer_format clears them.

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.update_agent(
    agent_name="my-research-bot",
    name="my-research-bot",
    description="Researches a topic and returns a sourced summary.",
    environments=["h/browser"],
    instructions="Always cite the page you took each claim from.",
    skills=["web-browse", "extract-data"],
)
print(agent.name)

200

{
  "name": "my-research-bot",
  "description": "Researches a topic and returns a sourced summary.",
  "environments": ["h/browser"],
  "model": null,
  "reasoning_effort": null,
  "instructions": "Always cite the page you took each claim from.",
  "subagents": null,
  "skills": ["web-browse", "extract-data"],
  "answer_format": null,
  "tools": null
}

Errors

Status	Cause
400	The name in the body does not match the URL identifier, or 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.
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	Body failed validation. Common cases: environments empty on an agent with no subagents or tools, invalid name shape.