---
title: "Update agent"
method: PUT
path: "/agents/{agentKey}"
tags: ["Agents"]
---

# Update agent

`PUT /agents/{agentKey}`

Apply a partial update to an existing agent configuration.

**Gateway contract**

The Node gateway validates the request body via Zod middleware before
forwarding to the Python agent service. The `agentKey` path param and
the request body are both validated. Query parameters are ignored by
the controller.

**Update semantics**

Only fields present in the request body are updated. `models` may be
omitted (the agent's existing models are kept), set to an empty array
(clears the agent's models so it falls back to the organization's
default LLM at chat time), or set to a non-empty array. When a
non-empty array is provided, the gateway Zod middleware requires at
least one object entry with `isReasoning: true`.

**Permissions**

The authenticated user must have `can_edit` on the agent (typically the
owner). Service-account and `shareWithOrg` transitions follow additional
Python business rules.

**Success response**

Returns a lightweight success envelope only. Use
`GET /agents/{agentKey}` to read the persisted agent after an update.

## Path parameters

- `agentKey` string, required

## Request body

- AgentUpdateRequest — Partial update payload for `PUT /agents/{agentKey}`. Every field is optional — only the fields present in the request body are updated. `models` may be omitted, set to an empty array to clear the agent's models (reverting it to the organization's default LLM at chat time), or set to a non-empty array. When a non-empty array is provided, the gateway Zod middleware (mirroring the Python backend) requires at least one object entry with `isReasoning: true`.
  - `name` string — Agent display name
  - `description` string — What the agent does
  - `startMessage` string — Initial greeting shown when conversation starts
  - `systemPrompt` string — System instructions for the agent
  - `instructions` string — Additional agent execution instructions
  - `models` AgentCreateModelEntry[] — Agent model configuration entries. Optional. An empty array clears the agent's models so it falls back to the organization's default LLM. When a non-empty array is present, the Zod middleware requires at least one object entry with `isReasoning: true`. String-only arrays are schema-valid but rejected at runtime with HTTP 400 unless empty.
    - union — Accepted model entry for `POST /agents/create`. The gateway accepts either a non-empty string model entry or an object entry with a required `modelKey`. The `models` array itself is optional and may be empty (the agent then uses the organization's default LLM). When the array is non-empty, it must include at least one object entry with `isReasoning: true`. String-only entries are schema-valid but, if present without any reasoning-flagged object entry, are rejected at the gateway with HTTP 400.
      - string
      - object
        - `modelKey` string, required
        - `modelName` string
        - `provider` string
        - `isReasoning` boolean
  - `tags` string[]
  - `shareWithOrg` boolean — Share agent with the organization
  - `isServiceAccount` boolean — Mark agent as a service account
  - `toolsets` AgentCreateToolset[] — Toolsets attached to the agent (instance-aware)
    - `name` 'calendar' | 'clickup' | 'confluence' | 'confluencedatacenter' | 'drive' | 'github' | 'gmail' | 'jira' | 'jiradatacenter' | 'lumos' | 'mariadb' | 'onedrive' | 'outlook' | 'redshift' | 'salesforce' | 'sharepoint' | 'slack' | 'teams' | 'zoom', required — Registered toolset name (lowercase) accepted by the create-agent gateway.
    - `displayName` string
    - `type` string
    - `instanceId` string
    - `instanceName` string
    - `tools` AgentCreateToolRef[]
      - `name` string, required
      - `fullName` string
      - `description` string
  - `knowledge` AgentCreateKnowledge[] — Knowledge sources connected to the agent
    - `connectorId` string, required
    - `filters` union
      - AgentKnowledgeFiltersParsed — Indexed scope for a knowledge connector: record-group ids and individual record ids. On GET, `filtersParsed` is this shape parsed from the stored `filters` JSON string.
        - `recordGroups` string[] — Deprecated/legacy: record-group ids for connector record-group scoping (e.g. Confluence spaces, Jira projects). No longer set for KB (Collection) entries — a KB is identified by its own `connectorId`, not by an id in this list.
        - `records` string[] — Individual record ids in scope.
      - string
      - unknown[]
        - unknown
  - `skills` AgentSkillAssignment[] — Complete replacement set of skills assigned to the agent. Send an empty array to clear all skill assignments.
    - `name` string, required — Lowercase skill name using single hyphens between segments.
  - `webSearch` union — Web-search attachment for an agent. Accepts either a provider string or an object with at least a `provider` field.
    - string
    - object
      - `provider` string, required
      - `providerKey` string
      - `providerLabel` string
      - `iconPath` string
  - `defaultReasoningEffort` 'none' | 'low' | 'medium' | 'high' | 'max', nullable — Agent-level reasoning effort used when a chat request omits its own.

## Response `200`

Agent updated successfully

- AgentUpdateResponse
  - `status` 'success', required
  - `message` string, required

## Other responses

- `400` — Gateway validation failure. Returned for missing/invalid `agentKey`, empty `models` array, `models` without a reasoning entry, malformed JSON, and other Zod schema violations. Syntactically invalid JSON may also surface as `500` depending on the Express parser.
- `401` — Missing or invalid authentication
- `403` — Forbidden — insufficient OAuth scope (`agent:write` required)
- `404` — Agent not found or inaccessible.
- `500` — Unexpected AI-backend or gateway failure.

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/revisions/64bfe76b130e/schema)