---
title: "Update displayName / capabilities / metadata [write]"
method: PATCH
path: "/agents/{id}"
---

# Update displayName / capabilities / metadata \[write\]

`PATCH /agents/{id}`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/agents/{id}`
- Auth: HTTP bearer

Omitted fields preserved; capabilities replaced whole (explicit [] revokes all; effective on the next capability call, no restart); metadata key-merged (null deletes a key); optional expectedVersion → 409 version_conflict on mismatch.

## Path parameters

- `id` string, required

## Request body

- PatchAgent
  - `displayName` string
  - `agentType` 'hermes' | 'claude_code' | 'codex' | 'openclaw' | 'pi' | 'dsh' | 'kimi_code' | 'opencode' | 'jev' | 'agoragentic_acp' | 'amp_acp' | 'auggie' | 'autohand' | 'cline' | 'codebuddy_code' | 'cortex_code' | 'corust_agent' | 'crow_cli' | 'cursor' | 'deepagents' | 'devin' | 'dimcode' | 'dirac' | 'factory_droid' | 'fast_agent' | 'gemini' | 'github_copilot_cli' | 'glm_acp_agent' | 'antigravity_acp' | 'goose' | 'grok_build' | 'harn' | 'junie' | 'kilo' | 'kimchi' | 'minimax_code' | 'minion_code' | 'mistral_vibe' | 'nova' | 'poolside' | 'qoder' | 'qwen_code' | 'sigit' | 'stakpak' | 'vtcode' | 'code_assistant' | 'docker_cagent' | 'kiro' | 'openhands' | 'muse_code' | 'workspace_acp': Moves the agent to another engine, checked as a new agent's would be. Sessions keep the engine they started on; new sessions use this one. Not for workspace-harness or image agents.
  - `llm` string: The model new sessions run; must be selectable on the agent's (next) agentType. Omitted with a new agentType = that engine's default model. A reasoning effort the new pair does not support is cleared.
  - `capabilities` string[]
  - `metadata` object
  - `environmentId` string, nullable: The environment sessions of this agent boot in when they name none; null clears, omitted preserves. Applies to sessions created afterwards.
  - `browserProfile` union: The browser this agent's sessions open with when they name none: mine, fresh or user:<user id>; null clears back to mine. Applies to sessions created afterwards
    - 'mine' | 'fresh' | 'workspace' | 'private'
    - string
  - `pluginsOff` string[]: Plugin ids switched off for this agent (app:gmail, tool:exa.web, chat:slack, bundle:<name>, skill:<id>, mcp:<id>); replaces the whole list, [] clears, omitted preserves. Tools, apps and chat apps stop at once in every chat of the agent; skills and MCP servers from the next provision. PUT /plugins/{id}/off switches one.
  - `vaultId` string, nullable: The vault every session of this agent carries; null clears, omitted preserves. Applies to sessions created afterwards.
  - `capabilityPolicies` object
  - `nativeToolPolicy` 'always_allow' | 'always_ask': Owner-only permission for native pod tools. Omitted preserves; changing permission requires idle sessions. There is no session override.
  - `hiringPolicy` 'allow' | 'deny': Whether this agent's sessions may bring in other agents as helpers. Omitted preserves. deny refuses the next helper a session tries to start; sessions created afterwards are not told how to hire.
  - `harnessVersion` string
  - `reasoningEffort` 'none' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra', nullable: Harness-native reasoning effort; null clears the pin and applies model-compatible normalization. Applies from the next provision/restart. Allowed values depend on agentType — agoragentic_acp: not supported; amp_acp: not supported; auggie: not supported; autohand: not supported; cline: not supported; codebuddy_code: not supported; cortex_code: not supported; corust_agent: not supported; crow_cli: not supported; cursor: not supported; deepagents: not supported; devin: not supported; dimcode: not supported; dirac: not supported; factory_droid: not supported; fast_agent: not supported; gemini: not supported; github_copilot_cli: not supported; glm_acp_agent: not supported; antigravity_acp: not supported; goose: not supported; grok_build: not supported; harn: not supported; junie: not supported; kilo: not supported; kimchi: not supported; minimax_code: not supported; minion_code: not supported; mistral_vibe: not supported; nova: not supported; poolside: not supported; qoder: not supported; qwen_code: not supported; sigit: not supported; stakpak: not supported; vtcode: not supported; code_assistant: not supported; docker_cagent: not supported; kiro: not supported; muse_code: not supported; openhands: not supported; hermes: none/minimal/low/medium/high/xhigh/max/ultra; claude_code: low/medium/high/xhigh/max; codex: none/minimal/low/medium/high/xhigh/max; openclaw: not supported; jev: not supported; pi: off/minimal/low/medium/high/xhigh/max; dsh: not supported; kimi_code: not supported; opencode: none/minimal/low/medium/high/xhigh/max; workspace_acp: not supported; models: claude-fable-5-1: low/medium/high/xhigh/max; claude-fable-5: low/medium/high/xhigh/max; claude-opus-5-5: low/medium/high/xhigh/max; claude-opus-5: low/medium/high/xhigh/max; claude-opus-4-8: low/medium/high/xhigh/max; claude-sonnet-5-5: low/medium/high/xhigh/max; claude-sonnet-5: low/medium/high/xhigh/max; claude-sonnet-4-6: low/medium/high/max; claude-haiku-5-5: low/medium/high/xhigh/max; claude-haiku-4-5: not supported; gpt-6.1-sol: low/medium/high/xhigh/max; gpt-6-astra: low/medium/high/xhigh/max; gpt-6-sol: none/low/medium/high/xhigh/max; gpt-6-luna: none/low/medium/high/xhigh/max; gpt-5.6-sol: none/low/medium/high/xhigh/max; gpt-5.6-terra: none/low/medium/high/xhigh/max; gpt-5.6-luna: none/low/medium/high/xhigh/max; gpt-5.5: none/low/medium/high/xhigh; gpt-4.1: not supported; deepseek-v4-pro: low/high/max; deepseek-flash: low/high/max; kimi-k3.1-pro: low/high/max; kimi-k3: low/high/max; kimi-k2.7-code: not supported; minimax-m3: not supported; muse-spark-1.1: minimal/low/medium/high/xhigh; muse-spark-1.2: minimal/low/medium/high/xhigh; muse-spark-1.3: minimal/low/medium/high/xhigh/max; minimax-m3.1-flash: low/medium/high/xhigh/max; gemini-4-argon: low/medium/high; gemini-3.5-flash-lite: low/medium/high; gemini-3.8-flash: low/medium/high; gemini-3.5-flash: low/medium/high; glm-5.3: low/high/max; glm-5.3-flash: low/high/max; grok-4.6: low/medium/high; grok-4.7: low/medium/high/xhigh
  - `skills` union[]: Replaces the whole skills array; omitted preserves. Applies from the next provision.
    - union
      - object
        - `type` 'skill', required
        - `skillId` string, required
        - `version` string
      - object
        - `type` 'github', required
        - `url` string, uri, required
        - `ref` string: Branch or commit SHA; default branch when omitted.
        - `tokenSecretRef` string: Agent secret key holding a clone token for private repos.
  - `mcpServers` object[]: Replaces the whole MCP server list; omitted preserves. Applies from the next provision.
    - `type` 'url'
    - `name` string, required
    - `url` string, uri, required
    - `tools` object
      - `include` string[]
      - `exclude` string[]
  - `hooks` object[]: Replaces the whole hook list; omitted preserves. Applies from the next provision.
    - `event` 'pre_session_start' | 'session_start' | 'user_prompt_submit' | 'pre_tool_use' | 'post_tool_use' | 'stop' | 'session_end', required
    - `command` string, required
    - `matcher` string
    - `timeout_s` integer
  - `handle` string, nullable: Workspace-scoped @handle for Slack/Lark mentions. Lower-case, 2–40 chars: [a-z0-9_]. Unique within a workspace; null clears.
  - `channel_settings` object, nullable: Channel persona settings for Slack/Lark. null resets to defaults (invitable: true, no description).
    - `invitable` boolean, required
    - `description` string
  - `runtime` union: BYO-code runtime config. {kind:'endpoint',protocol:'a2a'|'acp'|'mcp',url} or {kind:'image',image}. null clears (agent runs in the standard sandbox).
    - object
      - `kind` 'endpoint', required
      - `protocol` 'a2a' | 'acp' | 'mcp', required
      - `url` string, uri, required
    - object
      - `kind` 'image', required
      - `image` string, required
  - `expectedVersion` integer

## Response `200`

OK

- object
  - `agent` AgentDetail, required: Everything in the list item, plus configuration state.
    - `id` string: The agent id (agent_…) — the only address
    - `name` string
    - `displayName` string
    - `agentType` string
    - `llm` string
    - `harnessVersion` string, nullable
    - `reasoningEffort` 'none' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'null', nullable
    - `version` integer
    - `archived` boolean
    - `sessionCount` integer
    - `createdAt` string
    - `description` string, nullable
    - `prompt` string, nullable: The user prompt layer
    - `promptVersion` integer, nullable
    - `capabilities` string[]: The built-in capabilities this agent is granted — the exact set its sessions may execute (enforced; empty = none). Ids are listed at /docs/capabilities.
    - `capabilityPolicies` object: Per-capability permission policy map; omitted when no entries exist. always_allow: invoke without user confirmation. always_ask: prompt the session owner before every invocation. auto: reserved for future policy evaluation; currently prompts the session owner like always_ask.
    - `nativeToolPolicy` 'always_allow' | 'always_ask': Native pod-tool permission, independent of capabilities. Returned on create and detail responses; omitted legacy settings mean always_allow. Only the agent owner can change it, while sessions are idle.
    - `hiringPolicy` 'allow' | 'deny': Whether this agent's sessions may bring in other agents as helpers. allow unless set to deny. Returned on create and detail responses.
    - `mcpServers` object[]: Declared remote MCP server references, including tool filters; runtime authentication fields are never returned
      - `type` 'url'
      - `name` string, required
      - `url` string, uri, required
      - `tools` object
        - `include` string[]
        - `exclude` string[]
    - `hooks` object[]: Shell commands run in the session's pod at lifecycle events
      - `event` 'pre_session_start' | 'session_start' | 'user_prompt_submit' | 'pre_tool_use' | 'post_tool_use' | 'stop' | 'session_end', required
      - `command` string, required
      - `matcher` string
      - `timeout_s` integer
    - `metadata` object: Your key-merged client metadata
    - `environmentId` string, nullable: The environment sessions of this agent boot in when their create names none; ahead of the workspace default
    - `vaultId` string, nullable: The vault every session of this agent carries, after the vaults its create names and ahead of the workspace default
    - `defaultSessionId` string, nullable: The session conversation verbs target when addressed by agent id
    - `universe` string: Resolved universe slug

## Other responses

- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 11 warning, 39 info
  - added the new `code-review` enum value to the `agent/capabilities/items/` response property for the response status `200`
  - added the new `dictionary.define` enum value to the `agent/capabilities/items/` response property for the response status `200`
  - added the new `elevenlabs.music` enum value to the `agent/capabilities/items/` response property for the response status `200`
  - added the new `elevenlabs.tts` enum value to the `agent/capabilities/items/` response property for the response status `200`
  - …46 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/agents/:id/patch.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)