---
title: "Patch Agent"
method: PATCH
path: "/agents/{name}"
tags: ["agents"]
---

# Patch Agent

`PATCH /agents/{name}`

## Request

- Base URL: `https://api.agent4.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.agent4.io/agents/{name}`
- Auth: none declared

局部更新：只写请求里出现过的字段，其余原样留着。

404 而不是「创建一个」：PATCH 一个不存在的对象是调用方弄错了名字，替他建一个空壳只会让
那个错误更晚才被发现。

## Path parameters

- `name` string, required

## Request body

- AgentPatch: 只改传来的字段。 存在的理由是 `PUT` 是整体替换：`AgentIn` 每个字段都有默认值，一个漏掉 `soul` 的 PUT 会把 soul 静默清空。谁都不想要那个语义，所以每个调用方各自实现了一遍 GET→合并→PUT——包括我们 自己的 MCP 工具 `update_agent`，它的 docstring 专门解释过这件事。同一个坑被绕两次，就说明 该修的是坑。 区分「传了 null」和「没传」靠 `model_fields_set`：`greeting=null` 是清空开场白，不传是别动它。 列表字段（tools/skills/knowledge_bases）另备 `*_add` / `*_remove` **增量**语义： `tools=[...]` 是整表替换——调用方（尤其是通过 MCP 操作的智能体）想"加一个工具"时 发整表，就会把没读到的其它项挤掉；线上真出过（加 save_contact 顺手挤掉了 ip_geo/weather，无人察觉）。增删各自幂等：加已有的、删没有的都不报错。 同一字段的替换和增量可同用，先替换、再加、后删。
  - `soul` string, nullable
  - `task` string, nullable
  - `tools` string[], nullable
  - `tools_add` string[], nullable
  - `tools_remove` string[], nullable
  - `skills` string[], nullable
  - `skills_add` string[], nullable
  - `skills_remove` string[], nullable
  - `knowledge_bases` string[], nullable
  - `knowledge_bases_add` string[], nullable
  - `knowledge_bases_remove` string[], nullable
  - `history_window` integer, nullable
  - `max_output_tokens` integer, nullable
  - `tool_call_max_tokens` integer, nullable
  - `model` string, nullable
  - `published` boolean, nullable
  - `greeting` string, nullable
  - `auto_greeting` boolean, nullable
  - `auto_suggest` boolean, nullable
  - `suggest_prompt` string, nullable
  - `ask_forms` boolean, nullable
  - `proactive_cta` boolean, nullable
  - `cta_prompt` string, nullable
  - `no_match_reply` string, nullable
  - `reasoning` boolean, nullable
  - `grounding_required` boolean, nullable
  - `injection_guard` boolean, nullable
  - `public_sources` boolean, nullable
  - `ambiguity_check` boolean, nullable
  - `deep_research` boolean, nullable
  - `on_demand_context` boolean, nullable
  - `guard_escalation` boolean, nullable
  - `menu_items` string[], nullable

## Response `200`

Successful Response

- AgentOut
  - `name` string, required
  - `id` string, nullable
  - `alias` string, nullable
  - `soul` string, required
  - `task` string, required
  - `tools` string[], required
  - `skills` string[]
  - `knowledge_bases` string[]
  - `history_window` integer, nullable
  - `max_output_tokens` integer, nullable
  - `tool_call_max_tokens` integer, nullable
  - `model` string, nullable
  - `published` boolean
  - `greeting` string, nullable
  - `auto_greeting` boolean
  - `auto_suggest` boolean
  - `suggest_prompt` string, nullable
  - `ask_forms` boolean
  - `proactive_cta` boolean
  - `cta_prompt` string, nullable
  - `no_match_reply` string, nullable
  - `reasoning` boolean
  - `grounding_required` boolean
  - `injection_guard` boolean
  - `public_sources` boolean
  - `ambiguity_check` boolean
  - `deep_research` boolean
  - `on_demand_context` boolean
  - `guard_escalation` boolean
  - `menu_items` string[], nullable
  - `source` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/agent4/apis/chatagent-platform.md) · [All operations](https://skmtc.dev/agent4/apis/chatagent-platform/llms.txt) · [OpenAPI document](https://skmtc.dev/agent4/apis/chatagent-platform/revisions/18e58f082ce3?raw)