---
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. When `models` is
included, the gateway Zod middleware requires at least one model entry
and 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. When `models` is included, the gateway Zod middleware (mirroring the Python backend) requires at least one model entry and 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. When 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.
    - 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 must include at least one object entry with `isReasoning: true`. String-only entries are schema-valid but 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' | 'drive' | 'github' | 'gmail' | 'jira' | '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 (collections / KB roots) and individual record ids. First-party create/update flows set `recordGroups` and `records`. On GET, `filtersParsed` is this shape parsed from the stored `filters` JSON string.
        - `recordGroups` string[] — Record-group ids (e.g. knowledge-base roots) in scope.
        - `records` string[] — Individual record ids in scope.
      - string
      - unknown[]
        - unknown
  - `webSearch` union — Accepted web-search attachment for `POST /agents/create`. The gateway 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

## 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/versions/abd27cfefc73/schema)