---
title: "Update agent profile (role, description, capabilities, etc.)"
method: PUT
path: "/api/agents/{id}/profile"
tags: ["Agents"]
---

# Update agent profile (role, description, capabilities, etc.)

`PUT /api/agents/{id}/profile`

## Path parameters

- `id` string, required

## Request body

- object
  - `role` string
  - `description` string
  - `capabilities` string[]
  - `claudeMd` string
  - `soulMd` string
  - `identityMd` string
  - `setupScript` string
  - `toolsMd` string
  - `heartbeatMd` string
  - `avatar` object, nullable
    - `type` 'lucide', required
    - `icon` string, required
    - `color` string
  - `changeSource` string
  - `changedByAgentId` string
  - `changeReason` string

## Response `200`

Profile updated

- object
  - `id` string, required
  - `name` string, required
  - `isLead` boolean
  - `status` 'idle' | 'busy' | 'offline' | 'waiting_for_credentials', required
  - `description` string
  - `role` string
  - `capabilities` string[]
  - `claudeMd` string
  - `soulMd` string
  - `identityMd` string
  - `setupScript` string
  - `toolsMd` string
  - `heartbeatMd` string
  - `maxTasks` integer
  - `emptyPollCount` integer
  - `lastActivityAt` string, date-time
  - `provider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode' | 'acp'
  - `harnessProvider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode' | 'acp' | 'null', nullable
  - `credentialMissing` string[], nullable
  - `credStatus` AgentCredStatus
    - `ready` boolean, required
    - `missing` string[]
    - `satisfiedBy` 'env' | 'file' | 'side-effect-pending' | 'sdk-delegated' | 'null', nullable
    - `hint` string, nullable
    - `liveTest` AgentCredStatusLiveTest, nullable
      - `ok` boolean, required
      - `error` string, nullable
      - `latency_ms` number, required
      - `testedAt` number, required
    - `latestModel` AgentLatestModel, nullable
      - `model` string, required
      - `source` 'task' | 'agent_config' | 'adapter_default' | 'custom', required
      - `taskId` string, nullable
      - `harnessProvider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode' | 'acp' | 'null', nullable
      - `reportedAt` number, required
      - `reasoningEffort` 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `reportedAt` number, required
    - `reportKind` 'boot' | 'post_task'
    - `bedrock` AgentBedrockStatus, nullable
      - `region` string, required
      - `probedAt` number, required
      - `ready` boolean, required
      - `models` object[]
        - `id` string, required
        - `name` string, required
      - `error` string
  - `avatar` object
    - `type` 'lucide', required
    - `icon` string, required
    - `color` string
  - `createdAt` string, date-time, required
  - `lastUpdatedAt` string, date-time, required
  - `capacity` object, required
    - `current` integer, required
    - `max` integer, required
    - `available` integer, required

## Other responses

- `400` — Validation or identity-field budget error
- `404` — Agent not found

## Changes

- **2026-09-03** `0f5503f5cd28` — 3 warning
  - added the new `acp` enum value to the `allOf[#/components/schemas/Agent]/credStatus/oneOf[#/components/schemas/AgentCredStatus]/latestModel/harnessProvider` response property for the response status `200`
  - added the new `acp` enum value to the `allOf[#/components/schemas/Agent]/harnessProvider` response property for the response status `200`
  - added the new `acp` enum value to the `allOf[#/components/schemas/Agent]/provider` response property for the response status `200`
- **2026-08-18** `5c2324662674` — 1 info
  - added the optional property `profileSyncRejection` to the response with the `400` status
- **2026-08-07** `06cac6a7c5bc` — 3 info
  - added the media type `application/json` for the response with the status `200`
  - added the media type `application/json` for the response with the status `400`
  - added the media type `application/json` for the response with the status `404`
- **2026-08-06** `0a6cfa00296a` — 6 info
  - the `claudeMd` request property's maxLength was increased from `65536` to `262144`
  - the `heartbeatMd` request property's maxLength was increased from `65536` to `262144`
  - the `identityMd` request property's maxLength was increased from `65536` to `262144`
  - the `setupScript` request property's maxLength was increased from `65536` to `262144`
  - …2 more
- **2026-07-26** `27581e60c0cf` — 1 info
  - added the new optional request property `avatar`

[Change history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/agents/:id/profile/put.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/revisions/e0acd2155cad/schema)