---
title: "Update an agent"
method: PATCH
path: "/v1/agents/{identifier}"
tags: ["Agents"]
---

# Update an agent

`PATCH /v1/agents/{identifier}`

Update an agent by its external identifier.

## Path parameters

- `identifier` string, required

## Request body

- UpdateAgentRequestDto
  - `name` string
  - `description` string
  - `active` boolean
  - `behavior` AgentBehaviorDto
    - `acknowledgeOnReceived` boolean — Acknowledge incoming messages. On platforms that support a native typing indicator (e.g. Slack, WhatsApp, Microsoft Teams, Telegram), shows a "Typing…" indicator while the agent processes the message. On platforms that do not (e.g. Email), reacts with an "eyes" emoji to the first inbound message in a thread. Default: true
    - `reactionOnResolved` object, nullable — Cross-platform emoji name for resolved conversations (e.g. "check", "star"). Set to null to disable. Default: "check"
    - `subscriberAccess` 'open' | 'restricted' — Controls whether the agent accepts inbound messages from senders not yet linked to a subscriber, across all channels. "open" on managed agents auto-creates a lightweight subscriber so the agent can reply; on custom-code / self-hosted agents, the turn is forwarded to the bridge with a null subscriber. "restricted" rejects unknown senders with a managed denial reply (any runtime). Optional on update (partial PATCH). Persisted agents always have a value — managed create defaults to "open"; self-hosted create defaults to "restricted".
  - `bridgeUrl` string — Production bridge URL for this agent
  - `devBridgeUrl` string — Development bridge URL (set by npx novu dev)
  - `devBridgeActive` boolean — Whether the dev bridge override is active

## Response `200`

OK

- AgentResponseDto
  - `_id` string, required
  - `name` string, required
  - `identifier` string, required
  - `description` string
  - `behavior` AgentBehaviorDto, required
    - `acknowledgeOnReceived` boolean — Acknowledge incoming messages. On platforms that support a native typing indicator (e.g. Slack, WhatsApp, Microsoft Teams, Telegram), shows a "Typing…" indicator while the agent processes the message. On platforms that do not (e.g. Email), reacts with an "eyes" emoji to the first inbound message in a thread. Default: true
    - `reactionOnResolved` object, nullable — Cross-platform emoji name for resolved conversations (e.g. "check", "star"). Set to null to disable. Default: "check"
    - `subscriberAccess` 'open' | 'restricted' — Controls whether the agent accepts inbound messages from senders not yet linked to a subscriber, across all channels. "open" on managed agents auto-creates a lightweight subscriber so the agent can reply; on custom-code / self-hosted agents, the turn is forwarded to the bridge with a null subscriber. "restricted" rejects unknown senders with a managed denial reply (any runtime). Optional on update (partial PATCH). Persisted agents always have a value — managed create defaults to "open"; self-hosted create defaults to "restricted".
  - `active` boolean, required
  - `bridgeUrl` string — Production bridge URL
  - `devBridgeUrl` string — Development bridge URL (set by npx novu dev)
  - `devBridgeActive` boolean — Whether the dev bridge override is active
  - `runtime` 'self-hosted' | 'managed' — Whether the agent brain is self-hosted (bridge) or managed by a third-party provider
  - `visibility` 'public' | 'private' — Discovery scope of the agent. Always `public` today; reserved for the upcoming private-agents feature.
  - `managedRuntime` ManagedRuntimeResponseDto
    - `providerId` string, required
    - `integrationId` string, required
    - `externalAgentId` string, required
    - `externalEnvironmentId` string — The provider-side environment that hosts this agent. Hydrated from the linked integration credentials. Absent when the integration has not been provisioned.
    - `externalWorkspaceId` string — The provider-side workspace id used in console deep links. Defaults to `'default'` (the auto-created Default Workspace). Hydrated from the linked integration credentials.
    - `consoleUrl` string — Deep link to the agent in the provider console (e.g. platform.claude.com).
    - `tools` AgentToolDto[] — Live tools enabled on the managed-runtime provider for this agent. Sourced from the provider on read; omitted when the provider is temporarily unreachable.
      - `externalId` string, required
      - `name` string, required
      - `type` 'builtin' | 'custom', required
      - `description` string
    - `mcpServers` AgentMcpServerDto[] — MCP servers enabled on this agent, projected onto the runtime catalog `{ externalId, name, url }` shape. Mongo is the source of truth; the projection matches what the provider sees. Omitted when the provider read fails after a managed-agent write.
      - `externalId` string, required
      - `name` string, required
      - `url` string, required
    - `systemPrompt` string — System prompt used when invoking the agent.
  - `_environmentId` string, required
  - `_organizationId` string, required
  - `createdBy` string — Mongo user id of the user who created the agent
  - `createdAt` string, required
  - `updatedAt` string, required
  - `integrations` AgentIntegrationSummaryDto[]
    - `integrationId` string, required — Integration document id.
    - `providerId` string, required
    - `name` string, required
    - `identifier` string, required
    - `channel` 'in_app' | 'email' | 'sms' | 'chat' | 'push' | 'tool' — Channel type through which the message is sent
    - `active` boolean, required
  - `exceedsPlanLimit` boolean — Cloud only. `true` when the agent falls outside the organization plan agent limit (by creation order among active agents — inactive agents do not consume slots). Only plan limits produce this flag — system-capped organizations (enterprise/unlimited tiers) are never over-limit. Over-limit agents are still stored but will not respond to inbound messages until the plan is upgraded or older agents are deactivated.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — The agent was not found.
- `405` — Method Not Allowed
- `409` — Conflict
- `413` — Payload Too Large
- `414` — URI Too Long
- `415` — Unsupported Media Type
- `422` — Unprocessable Entity
- `429` — The client has sent too many requests in a given amount of time.
- `500` — Internal Server Error
- `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

---

[API](https://skmtc.net/novu/apis/deprecated-novu-api-use-openapi-json-yaml-instead.md) · [All operations](https://skmtc.net/novu/apis/deprecated-novu-api-use-openapi-json-yaml-instead/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/novu/deprecated-novu-api-use-openapi-json-yaml-instead/versions/986fe259fa85/schema)