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

# Update agent

`PATCH /agents/{agentId}`

Update an agent's name or paused state.

## Request body

- AgentUpdateRequest — Partial update to an agent's basic fields. At least one field must be provided.
  - `name` string — Updated name for the agent.
  - `isPaused` boolean — Set to true to pause the agent or false to resume it.

## Response `200`

Agent updated successfully

- Agent — A programmatic agent with scoped permissions and a spending policy, used to automate payment workflows.
  - `id` string, required — System-generated unique identifier for the agent.
  - `name` string, required — Human-readable name for the agent.
  - `customerId` string, required — The ID of the customer this agent operates on behalf of.
  - `isPaused` boolean, required — Whether the agent is currently paused. Paused agents cannot initiate any actions.
  - `isConnected` boolean, required — Whether the agent has been installed and connected (i.e., its device code has been redeemed).
  - `policy` AgentPolicy, required — Policy governing what an agent can do, how it executes actions, and its spending boundaries.
    - `permissions` AgentPermission[], required — List of permissions granted to the agent.
    - `defaultExecutionMode` 'AUTO' | 'APPROVAL_REQUIRED', required — Execution mode controlling whether agent actions require human approval. AUTO: The agent can execute actions autonomously without explicit approval. APPROVAL_REQUIRED: All agent actions require explicit human approval before execution.
    - `spendingLimits` AgentSpendingLimits, required — Spending limits that cap the agent's transaction amounts and frequency. All amount fields are integers in the smallest unit of the specified currency. When a transaction is denominated in a different currency, Grid converts using the exchange rate at evaluation time.
      - `currency` string, required — ISO 4217 currency code that all amount limits are denominated in.
      - `perTransactionLimit` integer, required — Maximum amount the agent can transfer in a single transaction.
      - `dailyLimit` integer, nullable — Maximum total amount the agent can transfer per day. Null means no daily limit.
      - `dailyTransactionLimit` integer — Maximum number of transactions the agent can initiate per day.
      - `monthlyLimit` integer, nullable — Maximum total amount the agent can transfer per month. Null means no monthly limit.
    - `accountRestrictions` AgentAccountRestrictions — Optional restrictions that limit the agent to specific accounts or override policy per account.
      - `allowedAccountIds` string[], nullable — If set, restricts the agent to operate only on the specified internal account IDs. Null means the agent can access all accounts.
      - `accountRules` AgentAccountRule[] — Per-account rules that override the agent's default policy for specific accounts.
        - `accountId` string, required — The internal account ID this rule applies to.
        - `executionMode` 'AUTO' | 'APPROVAL_REQUIRED' — Execution mode controlling whether agent actions require human approval. AUTO: The agent can execute actions autonomously without explicit approval. APPROVAL_REQUIRED: All agent actions require explicit human approval before execution.
        - `perTransactionLimit` integer, nullable — Per-transaction limit override, in the smallest unit of the relevant currency. Null inherits from the agent's spending limits.
    - `approvalThresholds` AgentApprovalThresholds — Thresholds that force approval for high-value transactions, overriding the default execution mode. When a transaction is denominated in a different currency than the threshold, Grid converts using the exchange rate at evaluation time.
      - `currency` string — ISO 4217 currency code that the amount threshold is denominated in. Required when amount is set.
      - `amount` integer, nullable — If set, any transaction above this amount (in the smallest unit of the specified currency) will require explicit approval even when the agent's defaultExecutionMode is AUTO. Null means no threshold override.
  - `usage` AgentUsage, required — Real-time counters tracking the agent's spending and transaction activity against its policy limits.
    - `dailyTransactionCount` integer, required — Number of transactions initiated by the agent today.
    - `dailySpend` integer, required — Total amount spent by the agent today, in the smallest unit of the policy's `spendingLimits.currency`.
    - `dailyResetDate` string, date — The date when daily usage counters will reset.
    - `monthlySpend` integer, required — Total amount spent by the agent this month, in the smallest unit of the policy's `spendingLimits.currency`.
    - `monthlyResetMonth` string — The year-month (YYYY-MM) when monthly usage counters will reset.
  - `createdAt` string, date-time, required — Creation timestamp.
  - `updatedAt` string, date-time, required — Last update timestamp.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Agent not found
- `500` — Internal service error

---

[API](https://skmtc.net/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.net/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/grid-api/versions/526036c12609/schema)