> ## Documentation Index > Fetch the complete documentation index at: https://docs.revoengine.com/llms.txt > Use this file to discover all available pages before exploring further. # Update an Agent > Update an Agent. The request enforces Agent roles, ownership, workspace boundaries, and lifecycle state. ## OpenAPI ````yaml /api-reference/openapi.json patch /api/v1/agents/{agentId} openapi: 3.0.0 info: title: RevoEngine Platform API description: Official RevoEngine Platform API documentation. version: 1.3.0 contact: name: Support email: support@revoengine.com termsOfService: https://docs.revoengine.com/tos servers: - url: https://api.revoengine.com description: Production security: [] tags: - name: Accounts description: Users, service accounts, API keys, status, and platform access. externalDocs: description: Identity and access guide url: https://docs.revoengine.com/operate/identity-and-access - name: Activity description: Snapshot-backed activity and version history. externalDocs: description: Observability guide url: https://docs.revoengine.com/operate/observability - name: Agent Memory description: Administrative access to durable Agent memory. externalDocs: description: Agent memory and workspaces guide url: https://docs.revoengine.com/ai/memory-and-workspaces - name: Agent Plugins description: Agent plugin definitions, synchronization, testing, and lifecycle. externalDocs: description: Agent plugins guide url: https://docs.revoengine.com/ai/plugins - name: Agents description: >- Agent definitions, runs, sessions, inboxes, memory, tools, workspaces, and lifecycle. externalDocs: description: Autonomous Agents guide url: https://docs.revoengine.com/ai/agents - name: Assistant description: >- Assistant threads, messages, responses, goals, reports, sharing, attachments, and control. externalDocs: description: Assistant guide url: https://docs.revoengine.com/ai/assistant - name: Automation description: >- Jobs, templates, schedules, events, webhooks, execution history, and lifecycle. externalDocs: description: Automation guide url: https://docs.revoengine.com/operate/automation - name: Chat description: Collaborative chat threads, messages, reactions, uploads, and attachments. externalDocs: description: Team Chat guide url: https://docs.revoengine.com/operate/chat - name: Component deployments description: >- Custom Node.js runtime deployment attempts, readiness, activation, and rollback. externalDocs: description: Custom Node.js guide url: https://docs.revoengine.com/build/custom-nodejs - name: Components description: Components, elements, versions, validation, activation, and lifecycle. externalDocs: description: Components guide url: https://docs.revoengine.com/build/components - name: Config description: Instance configuration, usage, logs, and cache administration. externalDocs: description: Instance settings guide url: https://docs.revoengine.com/platform/instance-settings - name: Database Cache description: Instance Database cache values and statistics. externalDocs: description: Database Cache guide url: https://docs.revoengine.com/operate/database-cache - name: Database Views description: Database Views, previews, refreshes, exports, and controlled data actions. externalDocs: description: Database Views guide url: https://docs.revoengine.com/operate/database-views - name: Databases description: Database definitions, data, audits, exports, cloning, and lifecycle. externalDocs: description: Databases guide url: https://docs.revoengine.com/operate/databases - name: Endpoints description: >- Endpoint definitions, activation, validation, generated OpenAPI, and statistics. externalDocs: description: Endpoints guide url: https://docs.revoengine.com/operate/endpoints - name: Files description: Compatibility file listing, preview, download, and deletion operations. externalDocs: description: Files compatibility guide url: https://docs.revoengine.com/operate/files - name: Groups description: Groups, membership, avatars, and lifecycle. externalDocs: description: Groups guide url: https://docs.revoengine.com/operate/groups - name: Me description: Current user profile, keys, avatar, and session information. externalDocs: description: Authentication guide url: https://docs.revoengine.com/developers/authentication - name: Preferences description: User and instance preference values. externalDocs: description: Platform UI guide url: https://docs.revoengine.com/platform/ui-tour - name: Role Groups description: Role groups, members, assigned roles, and lifecycle. externalDocs: description: Permissions guide url: https://docs.revoengine.com/operate/permissions - name: Roles description: Available platform roles and role details. externalDocs: description: Permissions guide url: https://docs.revoengine.com/operate/permissions - name: Search description: Cross-domain search over objects visible to the caller. externalDocs: description: Search and discovery guide url: https://docs.revoengine.com/platform/search - name: Secrets description: >- Secret definitions, revisions, activation, reveal, disable, and destruction. externalDocs: description: Secrets guide url: https://docs.revoengine.com/operate/secrets - name: Storage description: >- Storage workspaces, folders, objects, upload sessions, signed access, and lifecycle. externalDocs: description: Storage guide url: https://docs.revoengine.com/operate/storage externalDocs: description: Documentation url: https://docs.revoengine.com paths: /api/v1/agents/{agentId}: patch: tags: - Agents summary: Update an Agent description: >- Update an Agent. The request enforces Agent roles, ownership, workspace boundaries, and lifecycle state. operationId: AgentController_updateAgent parameters: - name: agentId required: true in: path schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAgentDto' responses: '200': description: '' security: - bearer: [] components: schemas: UpdateAgentDto: type: object properties: name: type: string description: Updated display name of the agent. example: Ops escalation coordinator minLength: 1 desc: type: string description: Updated operator-facing description. example: Owns production escalations and stakeholder updates. status: type: string description: Optional status transition, for example ACTIVE or PAUSED. enum: - ACTIVE - PAUSED - DISABLED example: PAUSED serviceAccountUserId: type: string description: Replacement service-account execution principal. format: uuid example: 11111111-1111-4111-8111-111111111111 ownerId: type: string description: Updated owner id. format: uuid example: 22222222-2222-4222-8222-222222222222 ownerType: type: string description: Updated owner type. example: GROUP metadata: type: object description: >- Replacement resource metadata. Values may use any JSON type. Maximum 16 KiB and 64 top-level keys. Top-level keys starting with "__" are reserved for backend use. example: costCenter: platform config: description: Replacement Agent identity and runtime defaults. example: model: configured-model executionMode: agent_loop maxActiveRootRuns: 2 maxConcurrentChildRuns: 2 maxTicks: 120 allOf: - $ref: '#/components/schemas/AgentConfigDto' policy: description: >- Replacement persisted policy constraints. Execution-time route metadata stays derived from the current turn. example: toolNames: - slack.send_message maxConcurrentChildRuns: 2 maxTicks: 24 allOf: - $ref: '#/components/schemas/AgentPolicyDto' version: type: number description: Optimistic locking version. example: 12 minimum: 0 AgentConfigDto: type: object properties: model: type: string description: Optional execution model identifier enabled for this instance. minLength: 1 reasoningEffort: type: string description: Reasoning effort passed to assistant threads. enum: - low - medium - high - xhigh executionMode: type: string description: Default execution mode used for Agent turns. enum: - interactive - execute - background - automation planningPolicy: type: string description: >- Durable planning policy default used for agent-loop turns. standard executes normally; review_required creates a reviewed plan before interactive execution. enum: - standard - review_required workMode: type: string description: >- Operating mode used to tune the agent toward the selected kind of work. enum: - balanced - coding - business - analyst - operator - creative persona: type: string description: >- Response persona applied beneath runtime policy and explicit agent instructions. enum: - friendly - pragmatic - professional - concise - calm - mentor - assertive systemInstructions: type: string description: >- Additional per-agent system instructions persisted with the definition. Runtime policy still has higher priority. minLength: 1 definition: description: >- Structured operator-owned Agent identity loaded on every autonomous turn. Learned memory cannot mutate this definition. allOf: - $ref: '#/components/schemas/AgentDefinitionDto' memoryPolicy: description: >- Durable cross-run memory defaults such as recall budget, retained summary size, and retention horizon. allOf: - $ref: '#/components/schemas/AgentMemoryPolicyDto' release: description: Release metadata for the current Agent definition. allOf: - $ref: '#/components/schemas/AgentReleaseConfigDto' automation: description: >- Enterprise automation defaults such as delivery mode, approval routing, and future delivery settings. allOf: - $ref: '#/components/schemas/AgentAutomationPolicyConfigDto' toolNames: description: >- Additional registered tool names associated with this agent. The runtime still exposes the complete callable tool registry. type: array items: type: string pluginIds: description: >- Default registry plugin ids attached to this agent. These are the agent-owned baseline attachments applied to every run unless additional runtime plugin ids are supplied. type: array items: type: string format: uuid plugins: description: >- Primary plugin contract surface. Plugins are provider-governed and define the executable agent-plugin surface. type: array items: $ref: '#/components/schemas/AgentPluginConfigDto' maxActiveRootRuns: type: number description: >- Maximum number of concurrently admitted root runs for this agent. Additional root runs remain queued until capacity is released. minimum: 1 maximum: 32 default: 1 maxChildRuns: type: number description: >- Maximum number of delegated child runs the parent may spawn per execution plan. minimum: 1 maximum: 128 maxConcurrentChildRuns: type: number description: >- Maximum number of delegated child runs that one parent may start concurrently. Remaining delegated steps wait for a later parent tick. minimum: 1 maximum: 32 default: 4 maxTicks: type: number description: Maximum number of ticks allowed for one run. minimum: 1 maximum: 1000 childFailureMode: type: string description: How the parent reacts when one delegated child fails. enum: - fail_parent - merge_partial AgentPolicyDto: type: object properties: defaultToolPermission: type: string description: >- Default approval mode applied to agent tool calls when no per-tool override exists. enum: - default - auto_review - full toolPermissions: type: object description: Per-tool approval mode overrides keyed by the runtime tool name. additionalProperties: enum: - default - auto_review - full toolNames: description: >- Additional policy-managed tool names. Tool permissions govern operations without truncating the callable registry. type: array items: type: string pluginIds: description: >- Policy-enforced registry plugin ids attached to this agent. These are governance-managed attachments and are merged in regardless of run-level plugin selection. type: array items: type: string format: uuid plugins: description: >- Policy-managed plugins merged with config plugins before execution-time routing narrows the active surface. type: array items: $ref: '#/components/schemas/AgentPluginConfigDto' maxActiveRootRuns: type: number description: >- Policy-enforced maximum number of concurrently admitted root runs for this agent. minimum: 1 maximum: 32 maxChildRuns: type: number description: Maximum number of delegated child runs allowed by policy. minimum: 1 maximum: 128 maxConcurrentChildRuns: type: number description: >- Policy-enforced maximum number of delegated child runs that one parent may start concurrently. minimum: 1 maximum: 32 maxTicks: type: number description: Maximum number of ticks allowed by policy. minimum: 1 maximum: 1000 childFailureMode: type: string description: How the parent reacts when one delegated child fails. enum: - fail_parent - merge_partial AgentDefinitionDto: type: object properties: identity: type: string description: Stable operator-owned identity of the Agent. maxLength: 500 mission: type: string description: Stable operator-owned mission of the Agent. maxLength: 2000 responsibilities: description: Responsibilities owned by the Agent. maxItems: 24 type: array items: type: string operatingPrinciples: description: Operator-owned principles applied on every Agent turn. maxItems: 24 type: array items: type: string successCriteria: description: Persistent completion criteria for the Agent role. maxItems: 24 type: array items: type: string AgentMemoryPolicyDto: type: object properties: enabled: type: boolean description: >- Whether the runtime may load and persist durable cross-run memory for this agent. default: true maxRecallEntries: type: number description: >- Maximum number of memory records the runtime should recall into one run. minimum: 1 maximum: 64 maxRecallChars: type: number description: >- Total character budget reserved for compact recalled memory summaries across one run. minimum: 128 maximum: 64000 AgentReleaseConfigDto: type: object properties: versionLabel: type: string description: Operator-facing release label such as 2026.04.10 or canary-1. minLength: 1 changeSummary: type: string description: Short operator-facing change summary for the current definition. minLength: 1 AgentAutomationPolicyConfigDto: type: object properties: defaultDeliveryMode: type: string description: >- Default trigger delivery mode for automation when the caller does not override it explicitly. enum: - INBOX - DIRECT_RUN approvalRouting: description: >- Approval-routing metadata reserved for enterprise automation escalation and operator delegation. allOf: - $ref: '#/components/schemas/AgentAutomationApprovalRoutingDto' notificationPolicy: description: >- Notification and delivery policy reserved for idempotent inbox fan-out and future chat delivery surfaces. allOf: - $ref: '#/components/schemas/AgentAutomationNotificationPolicyDto' AgentPluginConfigDto: type: object properties: contractVersion: type: number description: Plugin contract version for the governed runtime surface. default: 1 minimum: 1 maximum: 1 id: type: string description: Stable plugin id used by the agent runtime. minLength: 1 kind: type: string description: Plugin execution provider kind. enum: - tools - mcp_server - skill - package default: tools name: type: string description: Operator-facing plugin name. minLength: 1 description: type: string description: Optional plugin description. routing: description: >- Canonical English capability metadata used for tool selection. Operator-facing content may remain localized. allOf: - $ref: '#/components/schemas/AgentPluginRoutingConfigDto' executionMode: type: string description: Execution mode expected for the plugin provider. enum: - sync - background componentId: type: string description: Component id executed when this plugin runs. minLength: 1 componentVersion: type: number description: Optional fixed component version. minimum: 0 componentToolset: description: >- Multiple governed tool contracts backed by the same component implementation. allOf: - $ref: '#/components/schemas/AgentPluginComponentToolsetDto' mcpServer: description: Remote MCP server configuration used when `kind` is `mcp_server`. allOf: - $ref: '#/components/schemas/AgentPluginMcpConfigDto' mcpToolset: description: >- Per-tool MCP governance and loading configuration used when `kind` is `mcp_server`. allOf: - $ref: '#/components/schemas/AgentPluginMcpToolsetDto' skill: description: Markdown skill configuration used when `kind` is `skill`. allOf: - $ref: '#/components/schemas/AgentPluginSkillConfigDto' package: description: >- Markdown package manifest and dependency ids used when `kind` is `package`. allOf: - $ref: '#/components/schemas/AgentPluginPackageConfigDto' inputSchema: type: object description: >- Strict structured input schema exposed to discovery and runtime validation. Must be an object schema with additionalProperties=false and descriptions on every declared property. outputSchema: type: object description: Structured output schema expected from the plugin provider. approvalPolicy: description: Approval contract enforced before execution. allOf: - $ref: '#/components/schemas/AgentPluginApprovalConfigDto' mutationIntent: type: string description: Declared mutation intent used for governance and approval safety. enum: - read - write - destructive - external reversibility: type: string description: Declared reversibility of the plugin side effects. enum: - reversible - operator_reversible - irreversible - unknown targetScope: type: string description: Primary runtime scope impacted when the plugin executes. enum: - assistant_thread - agent - tenant - external sideEffectSummary: type: string description: >- Concise side-effect declaration recorded in approval, evidence, and audit surfaces. sideEffectCategories: description: >- Normalized side-effect categories used for governance and operator review. type: array items: type: string timeoutMs: type: number description: Maximum runtime in milliseconds. minimum: 1000 example: 30000 resultMaxBytes: type: number description: Maximum serialized result size in bytes. minimum: 512 autoDiscovery: type: boolean description: >- Whether the plugin should be surfaced as summary-only discovery context before explicit attachment. default: false enabled: type: boolean description: Whether the plugin is enabled for execution. default: true AgentAutomationApprovalRoutingDto: type: object properties: mode: type: string description: >- How non-interactive automation should behave when a later phase adds approval delegation. enum: - block - delegate - notify delegateUserIds: description: >- Users who should receive delegated approval or escalation when automation cannot continue autonomously. type: array items: type: string format: uuid notifyUserIds: description: >- Users who should be notified when automation reaches an approval gate or escalation path. type: array items: type: string format: uuid AgentAutomationNotificationPolicyDto: type: object properties: dedupeWindowSeconds: type: number description: >- Suggested dedupe window for downstream delivery or inbox fan-out keyed by one automation trigger. minimum: 0 maximum: 604800 maxAttempts: type: number description: >- Suggested maximum delivery attempts for downstream notification or future chat delivery workers. minimum: 1 maximum: 32 auditTrail: type: boolean description: >- Whether automation-triggered delivery should retain an audit trail inside durable trigger state and future delivery workers. default: true AgentPluginRoutingConfigDto: type: object properties: title: type: string description: >- Canonical English capability title used for tool selection. Display names may remain localized. summary: type: string description: >- Canonical English capability summary used for tool selection. Display descriptions may remain localized. AgentPluginComponentToolsetDto: type: object properties: defaultConfig: description: Default governance and loading policy for component-backed tools. allOf: - $ref: '#/components/schemas/AgentPluginComponentToolConfigDto' tools: type: object description: Component-backed tools keyed by stable capability name. AgentPluginMcpConfigDto: type: object properties: transport: type: string description: Remote MCP transport supported by the SaaS runtime. enum: - streamable_http - sse url: type: string description: Absolute HTTPS endpoint for the remote MCP server. manifestTtlMs: type: number description: Manifest cache time-to-live in milliseconds. minimum: 1000 connectTimeoutMs: type: number description: Connection and handshake timeout in milliseconds. minimum: 1000 example: 30000 toolNamePrefix: type: string description: Prefix used to derive local MCP tool names from remote tool names. minLength: 1 authMode: type: string description: Auth mode used when calling the remote MCP server. enum: - none - bearer - basic - header bearerSecretId: type: string description: Secret id containing the bearer token. minLength: 1 bearerSecretDataId: type: string description: Optional secret data revision id for the bearer token binding. minLength: 1 basicUsername: type: string description: Optional username for basic auth. basicPasswordSecretId: type: string description: Secret id containing the basic auth password. minLength: 1 basicPasswordSecretDataId: type: string description: >- Optional secret data revision id for the basic auth password binding. minLength: 1 headers: description: >- Additional header bindings resolved from tenant secrets before calling the MCP server. type: array items: $ref: '#/components/schemas/AgentPluginMcpHeaderBindingDto' AgentPluginMcpToolsetDto: type: object properties: defaultConfig: description: >- Default governance and loading policy for tools discovered from this MCP server. allOf: - $ref: '#/components/schemas/AgentPluginMcpToolConfigDto' configs: type: object description: Per-remote-tool overrides keyed by remote tool name. AgentPluginSkillConfigDto: type: object properties: format: type: string description: Skill content format. Markdown is the only supported v1 format. enum: - markdown default: markdown content: type: string description: >- Markdown instruction content loaded into the assistant runtime when the plugin is attached. format: markdown minLength: 1 pluginIds: description: Registry plugin ids declared as one-level skill dependencies. type: array items: type: string format: uuid maxPromptChars: type: number description: Maximum number of skill content characters allowed into one prompt. minimum: 256 maximum: 64000 AgentPluginPackageConfigDto: type: object properties: externalId: type: string description: Stable package identifier used by this plugin definition. minLength: 1 example: com.revo.notion format: type: string description: Package content format. Markdown is the only supported v1 format. enum: - markdown default: markdown content: type: string description: >- Markdown instruction content loaded into the assistant runtime when the package is attached. format: markdown minLength: 1 pluginIds: description: Registry plugin ids declared as package dependencies. type: array items: type: string format: uuid metadata: description: >- Disabled marketplace-facing package metadata reserved for catalog publishing. readOnly: true deprecated: true allOf: - $ref: '#/components/schemas/AgentPluginPackageMetadataDto' maxPromptChars: type: number description: >- Maximum number of package content characters allowed into one prompt. minimum: 256 maximum: 64000 required: - externalId AgentPluginApprovalConfigDto: type: object properties: mode: type: string description: >- How plugin execution approval is enforced before the provider call is made. enum: - none - always - conditional safetyTier: type: string description: Safety tier enforced for approval and mutation governance. enum: - read - write - destructive - external - execute AgentPluginComponentToolConfigDto: type: object properties: enabled: type: boolean description: >- Whether this component-backed tool is enabled for runtime selection and execution. deferLoading: type: boolean description: >- Whether this component-backed tool is deferred behind discovery instead of eagerly exposed. alias: type: string description: Explicit local tool alias exposed to the runtime when set. minLength: 1 title: type: string description: Operator-facing title for this component-backed tool. description: type: string description: Tool-specific description exposed to the assistant runtime. entrypoint: type: string description: >- Stable implementation entrypoint passed to the component in api.input().agentTool.entrypoint. Defaults to the tool key. minLength: 1 inputs: type: object description: >- Static runtime inputs passed to the component under api.input().agentTool.inputs. popResult: type: string description: >- Named component result to return when the component executor supports result popping. minLength: 1 inputSchema: type: object description: >- Strict structured input schema exposed for this tool. The component receives matching arguments under api.input().agentTool.args. Must be an object schema with additionalProperties=false and descriptions on every declared property. outputSchema: type: object description: Structured output schema expected from this tool. approvalPolicy: description: Per-tool approval contract enforced before execution. allOf: - $ref: '#/components/schemas/AgentPluginApprovalConfigDto' mutationIntent: type: string description: Declared mutation intent for this component-backed tool. enum: - read - write - destructive - external reversibility: type: string description: Declared reversibility for this component-backed tool. enum: - reversible - operator_reversible - irreversible - unknown targetScope: type: string description: Primary runtime scope impacted by this component-backed tool. enum: - assistant_thread - agent - tenant - external sideEffectSummary: type: string description: Concise side-effect declaration recorded for this tool. sideEffectCategories: description: >- Normalized side-effect categories used for governance and operator review. type: array items: type: string AgentPluginMcpHeaderBindingDto: type: object properties: name: type: string description: Header name sent to the remote MCP server. minLength: 1 secretId: type: string description: Secret id containing the header value. minLength: 1 secretDataId: type: string description: >- Optional secret data revision id when the binding should pin a specific secret revision. minLength: 1 value: type: string description: >- Optional static header value used when the binding does not read from a secret. prefix: type: string description: >- Optional static prefix added before the resolved secret value, for example `Bearer `. AgentPluginMcpToolConfigDto: type: object properties: enabled: type: boolean description: Whether the tool is enabled for runtime selection and execution. deferLoading: type: boolean description: >- Whether the tool is deferred behind discovery instead of eagerly exposed. alias: type: string description: Explicit local tool alias exposed to the runtime when set. minLength: 1 approvalPolicy: description: Per-tool approval contract enforced before execution. allOf: - $ref: '#/components/schemas/AgentPluginApprovalConfigDto' mutationIntent: type: string description: Declared mutation intent for this remote tool override. enum: - read - write - destructive - external reversibility: type: string description: Declared reversibility for this remote tool override. enum: - reversible - operator_reversible - irreversible - unknown targetScope: type: string description: Primary runtime scope impacted by this remote tool override. enum: - assistant_thread - agent - tenant - external sideEffectSummary: type: string description: >- Concise side-effect declaration recorded for this remote tool override. AgentPluginPackageMetadataDto: type: object properties: avatarUrl: type: string description: Package avatar or icon URL shown in package catalogs. format: uri websiteUrl: type: string description: Package website URL. format: uri documentationUrl: type: string description: Package documentation URL. format: uri termsOfServiceUrl: type: string description: Package terms of service URL. format: uri privacyPolicyUrl: type: string description: Package privacy policy URL. format: uri supportUrl: type: string description: Package support URL. format: uri publisherName: type: string description: Publisher display name. minLength: 1 publisherUrl: type: string description: Publisher website URL. format: uri license: type: string description: Package license label. minLength: 1 categories: description: Package catalog categories. type: array items: type: string tags: description: Package search tags. type: array items: type: string securitySchemes: bearer: scheme: bearer bearerFormat: JWT description: Bearer JWT token or API Key (sk-*). type: http ````