# Update an agent

`PUT /apis/cra.diagrid.io/v1beta1/projects/{ProjectId}/agents/{AgentId}`

Update an existing agent by replacing its configuration.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ProjectId` | string | Yes | Unique identifier of the project. |
| `AgentId` | string | Yes | Unique identifier of the agent. |

### Request body

The agent configuration to apply.

`application/json`

- `apiVersion` (string)
- `kind` (string)
- `metadata` (object)
  - `name` (string)
  - `uid` (string)
  - `resourceVersion` (integer)
  - `createdAt` (string)
  - `updatedAt` (string)
  - `deletedAt` (string)
  - `labels` (object<string, string>)
  - `annotations` (object)
- `spec` (object) — Required. Spec is the desired state of an Agent.
  - `projectId` (string) — Required. Read-only. Immutable. ProjectID is server-derived from the request path: read-only and immutable.
  - `protocol` (string) — Protocol selects the application-channel protocol the sidecar uses to communicate with the agent endpoint: "http" (default) or "grpc". One of: `http`, `grpc`.
  - `endpoint` (object) — Endpoint is the reachable URL of the user's agent workload.
    - `url` (string) — Required.
    - `token` (string) — Write-only. Token authenticates calls from the dataplane to the agent endpoint. Write-only: responses never include it.
  - `workflowArchive` (object) — WorkflowArchiveSpec selects which terminal workflow states have their history archived on purge and where the archive is written. Archiving is enabled when a destination binding is set.
    - `completed` (boolean) — Completed archives workflows that reach the Completed terminal state.
    - `failed` (boolean) — Failed archives workflows that reach the Failed terminal state.
    - `terminated` (boolean) — Terminated archives workflows that reach the Terminated terminal state.
    - `destination` (object) — WorkflowArchiveDestination identifies the archive output binding.
      - `binding` (string) — Binding is the output-binding component name. Empty disables archiving.
      - `type` (string) — Type is the binding component type (e.g. "bindings.aws.s3").
- `status` (object) — AgentStatus is the observed state of an Agent.
  - `status` (string)
  - `messages` (object[])
    - `message` (string)
  - `instances` (object<string, object>) — Instances holds the resource's processing status keyed by the region host it runs on.
    - `status` (string)
    - `messages` (object[])
      - `message` (string)
    - `processedSpecVersion` (integer (int64))
    - `regionHostId` (string)
  - `managedAppId` (string) — ManagedAppID is the name of the AppID this Agent owns and manages as its backing identity.
  - `appIds` (object[]) — AppIDs embeds the AppID this Agent owns and manages, including its status.apiToken. Populated only when a Get request carries include=appids.
    - `apiVersion` (string) — Required.
    - `kind` (string) — Required.
    - `metadata` (object) — Required.
      - `uid` (string)
      - `name` (string) — Required.
      - `namespace` (string) — Required.
      - `resourceVersion` (integer (int64))
      - `statusVersion` (integer (int64))
      - `createdAt` (string)
      - `updatedAt` (string)
      - `deletedAt` (string)
      - `finalizers` (string[]) — if no finalizers are set the resource will be deleted from the database directly when calling MarkForDelete, delete event is fired normally then the event dispatcher will detect that situation and delete the resource from the cache.
      - `annotations` (object)
      - `hash` (string)
      - `labels` (object<string, string>)
    - `spec` (object) — Required. AppIdentitySpec is the user-facing specification of an App ID.
      - `projectId` (string) — Required. Read-only. Immutable. ProjectID is server-derived from the request path; the client-supplied value is ignored.
      - `apiTokenRevision` (integer)
      - `appEndpoint` (object) — AppEndpoint is the application endpoint configuration of an App ID.
        - `url` (string)
        - `clientTimeoutSeconds` (integer)
        - `token` (string) — Write-only. Token authenticates calls from the dataplane to the app endpoint. It can only be written: responses never include it, the app token is only returned as .status.appToken.
      - `healthCheck` (object)
        - `path` (string) — used for HTTP e.g. /health.
        - `probe` (object)
          - `enabled` (boolean)
          - `intervalInSec` (integer (int32))
          - `timeoutInMs` (integer (int32))
          - `failureThreshold` (integer (int32))
      - `protocol` (string)
      - `appConfig` (string)
      - `resiliency` (object)
        - `retryPolicyName` (string)
        - `timeoutPolicyName` (string)
        - `circuitBreakerPolicyName` (string)
      - `maxBodySize` (string)
      - `external` (boolean) — Immutable.
      - `appContainer` (object) — AppContainerSpec holds configuration for an app container that runs alongside a sidecar.
        - `image` (string)
        - `port` (integer)
        - `pullPolicy` (string)
        - `command` (string[])
        - `args` (string[])
        - `env` (object<string, string>)
        - `files` (object<string, string>)
      - `workflowArchive` (object) — WorkflowArchiveSpec selects which terminal workflow states have their history archived on purge and where the archive is written. Archiving is enabled when a destination binding is set.
        - `completed` (boolean) — Completed archives workflows that reach the Completed terminal state.
        - `failed` (boolean) — Failed archives workflows that reach the Failed terminal state.
        - `terminated` (boolean) — Terminated archives workflows that reach the Terminated terminal state.
        - `destination` (object) — WorkflowArchiveDestination identifies the archive output binding.
          - `binding` (string) — Binding is the output-binding component name. Empty disables archiving.
          - `type` (string) — Type is the binding component type (e.g. "bindings.aws.s3").
      - `workflowNotifications` (object) — WorkflowNotificationsSpec selects which workflow outcomes raise an alert. Completed workflows are not selectable: the policy reports outcomes that need someone's attention.
        - `name` (string) — Name is a regular expression the workflow name must match in full. Empty matches every workflow.
        - `failed` (boolean) — Failed notifies workflows that reach the Failed terminal state.
        - `terminated` (boolean) — Terminated notifies workflows that reach the Terminated terminal state.
        - `stalled` (boolean) — Stalled notifies workflows that reach the Stalled state.
        - `rootOnly` (boolean) — RootOnly restricts notifications to workflows with no parent, so one failing parent does not also alert for each of its children.
    - `status` (object) — AppIdentityStatus represents the status of an application identity.
      - `status` (string) — Status is the current processing status of the resource.
      - `updatedAt` (string) — UpdatedAt is the time of the last status update.
      - `messages` (object[]) — Messages contains any status messages, such as error details.
        - `message` (string)
      - `instances` (object[]) — Instances includes the status for each instance of the resource.
        - `cluster` (string) — Cluster is the name of the cluster hosting this instance.
        - `region` (string) — Region is the region where the instance is located (e.g. "us-east-1").
        - `placementId` (string) — PlacementID is the project placement this instance belongs to (e.g. "1").
        - `status` (string) — Status is the current processing status of the resource.
        - `updatedAt` (string) — UpdatedAt is the time of the last status update.
        - `messages` (object[]) — Messages contains any status messages, such as error details.
          - `message` (string)
      - `apiToken` (string) — APIToken is omitted unless the caller has the appIdCredentials.get permission.
      - `appToken` (string)
      - `resiliencyStatus` (object)
        - `retryPolicyName` (string)
        - `timeoutPolicyName` (string)
        - `circuitBreakerPolicyName` (string)
      - `resiliency` (object)
        - `projectId` (string) — Required. Immutable.
        - `resiliencySpec` (object) — Required. ResiliencySpec is the Dapr resiliency specification (policies and targets), based on the upstream Dapr Resiliency API. Fields present upstream but not listed here are not supported in Catalyst.
          - `policies` (object)
            - `timeouts` (object<string, string>)
            - `retries` (object<string, object>)
              - *(nested fields omitted at this depth)*
            - `circuitBreakers` (object<string, object>)
              - *(nested fields omitted at this depth)*
          - `targets` (object)
            - `apps` (object<string, object>)
              - *(nested fields omitted at this depth)*
            - `components` (object<string, object>)
              - *(nested fields omitted at this depth)*
        - `scopes` (string[])
      - `spiffeId` (string) — SpiffeID is the single workload identity this App ID is reported under: the identity it is issued in the first of its project's regions by name. It does not move when a region is promoted, and a workload running in any other region of the project presents a different identity. Use regionIdentities to pre-trust the identity of every region instead of following this one.
      - `spiffeIds` (string[]) — SpiffeIDs is every workload identity this App ID is issued, one per region its project is placed in, in the same order as regionIdentities. Deprecated: use regionIdentities instead, which names the region each identity belongs to.
      - `regionIdentities` (object[]) — RegionIdentities lists the workload identity this App ID is issued in every region its project is placed in, one entry per region, ordered by region name. It is spiffeIds with the region each identity belongs to named, so a reader does not have to take it from the trust domain. Pre-trust every entry in an external identity federation: a project spread over a region group runs under a different identity in each of its regions, and which one a workload presents follows the region it runs in. The OIDC issuer that verifies JWTs minted for an identity is the region's, and is read from that region (status.endpoints.oidc).
        - `region` (string) — Region is the region the identity is issued in. Read that region to get the OIDC issuer verifying JWTs minted for this identity, and the trust anchors verifying its certificates: both are region properties, served on the region's own status.endpoints.
        - `spiffeId` (string) — SpiffeID is the SPIFFE ID workloads of this App ID present in that region.
      - `externalBootstrapConfig` (string) — ExternalBootstrapConfig is the bootstrap YAML configuration for external appIDs. It contains everything an external workload needs to connect to the data plane, including the required endpoints and the join token.
      - `isActive` (boolean) — IsActive indicates if the app identity is active, if the sidecar has performed API operations recently.
      - `workflowsConnected` (boolean) — WorkflowsConnected indicates if the app identity has workflow workers currently connected.
      - `clientType` (string) — ClientType is the identity-view classification of this App ID — "app", "agent", or "mcpserver".
      - `appEndpointStatus` (string) — Deprecated: use appHealthCheckStatus instead.
      - `appHealthCheckStatus` (object) — AppIdentityAppHealthCheckStatus represents the health check status of an application identity.
        - `ishealthy` (boolean)
        - `timestamp` (string)
        - `reason` (string)
      - `events` (object) — AppIdentityEvents represents events from an application identity.
        - `errors` (object[])
          - `cluster` (string) — Cluster is the name of the cluster the event originated from.
          - `message` (string)
          - `timestamp` (string (date-time))

Example:

```json
{
  "apiVersion": "cra.diagrid.io/v1beta1",
  "kind": "Agent",
  "metadata": {
    "name": "orders-agent"
  },
  "spec": {
    "projectId": "my-project",
    "endpoint": {
      "url": "https://orders-agent.example.com"
    }
  }
}
```

## Responses

### 202 — Accepted for asynchronous processing.

### 404 — The agent was not found.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### default — Unexpected error.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.