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

# Update agent

`PATCH /agents/{agentId}`

Update an agent's mutable fields. Changing `slug` (the agent handle segment) requires a non-delegated user session on an active, verified party; renaming or clearing a slug releases the previous value into a 14-day hold.

## Path parameters

- `agentId` string, required — Agent ID

## Headers

- `Idempotency-Key` string, required
- `X-Agent-ID` string, nullable
- `X-Instance-ID` string, nullable

## Request body

- object
  - `data` object, required — Resource object
    - `attributes` object, required — Agent update attributes
      - `name` string, nullable — Updated name for the agent
      - `description` string, nullable — Updated description
      - `slug` string, nullable — Agent handle slug (the segment after the party handle in "@handle-slug"). Slugs use lowercase letters, digits, interior dots, or underscores; hyphen is reserved as the party/agent separator. A string sets or renames it, null clears it, omitted leaves it unchanged; empty string is rejected (use null to clear instead). Renaming or clearing releases the previous slug into a 14-day hold. Requires a non-delegated user session on an active, verified party; other actors receive a 403.
      - `limits` object, nullable — Spend caps. When present the object is a full replacement: a null or omitted field clears that window's cap. null clears every cap; omitted leaves limits unchanged. AGENT actors must not change the limits that gate them: supplying `limits` as an AGENT actor fails with 403.
        - `perTransaction` integer, nullable — Positive per-transaction limit in cents. null means no per-transaction limit.
        - `perDay` integer, nullable — Positive daily (UTC) spend cap in cents. null means no daily limit.
        - `perMonth` integer, nullable — Positive calendar-month (UTC) spend cap in cents. null means no monthly limit.

## Response `200`

Successful Response

- object
  - `data` object, required
    - `type` 'agent', required — Resource type
    - `id` string, required — Resource ID
    - `attributes` object, required — Resource attributes
      - `name` string, required — Agent display name
      - `description` string, nullable, required — Agent description
      - `handle` string, nullable, required — Agent handle composed from the owning party's handle and the agent slug (e.g. "@acme-bot"), or null when either part is unclaimed
      - `status` 'ACTIVE' | 'REVOKED', required — Agent status
      - `limits` object, nullable, required — Spend caps for actions this agent initiates on its owner's party. null = no limits. Stored as Policies(scope=Agent(id)) in the policy service.
        - `perTransaction` integer, nullable — Positive per-transaction limit in cents. null means no per-transaction limit.
        - `perDay` integer, nullable — Positive daily (UTC) spend cap in cents. null means no daily limit.
        - `perMonth` integer, nullable — Positive calendar-month (UTC) spend cap in cents. null means no monthly limit.
      - `createdAt` string, date-time, nullable, required — When this agent was created
      - `createdBy` string, nullable, required — User who created this agent (usr_*)
      - `lastActiveAt` string, date-time, nullable, required — Timestamp of the agent's most recent authenticated request, or null if it has never made one. Updated at most about once per minute, so it reflects recent activity at minute granularity rather than exactly.
    - `relationships` object, required — Resource relationships
      - `party` object, required — Party that owns the agent
        - `data` object, required — Related resource identifier
          - `type` 'party', required — Resource type
          - `id` string, required

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found — returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

---

[API](https://skmtc.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/natural/natural-api/revisions/8cc2aed45847/schema)