---
title: "Bind or unbind an agent to a pool"
method: PUT
path: "/api/agents/{id}/runtime-pool"
tags: ["Runtime pools"]
---

# Bind or unbind an agent to a pool

`PUT /api/agents/{id}/runtime-pool`

## Request

- Base URL: `http://localhost:3013`
- URL: `http://localhost:3013/api/agents/{id}/runtime-pool`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Request body

- object
  - `poolId` string, nullable, required

## Response `200`

Success

- object
  - `agent` Agent, required
    - `id` string, required
    - `name` string, required
    - `isLead` boolean
    - `status` 'idle' | 'busy' | 'offline' | 'waiting_for_credentials', required
    - `runtimePoolId` string, nullable
    - `runtimeProvisionAttempts` integer
    - `runtimeProvisionRetryAt` string, nullable
    - `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' | 'dsh' | 'amp' | 'cursor' | 'grok' | 'fx'
    - `harnessProvider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode' | 'acp' | 'dsh' | 'amp' | 'cursor' | 'grok' | 'fx' | '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
        - `warning` string
        - `keys` AgentCredStatusKeyResult[]
          - `keyType` string, required
          - `index` number, required
          - `suffix` string, required
          - `ok` boolean, required
          - `error` string
          - `httpStatus` number
          - `latency_ms` 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' | 'dsh' | 'amp' | 'cursor' | 'grok' | 'fx' | '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
      - `opencodeGo` AgentOpencodeGoStatus, nullable
        - `probedAt` number, required
        - `models` string[]
      - `acp` AgentAcpStatus, nullable
        - `target` 'opencode' | 'gemini' | 'copilot' | 'qwen' | 'kiro' | 'goose' | 'custom', required
        - `configOptions` union[], required
          - union
            - object
              - …
            - object
              - …
        - `reportedAt` number, required
    - `avatar` object
      - `type` 'lucide', required
      - `icon` string, required
      - `color` string
    - `slackIcon` union
      - object
        - `type` 'emoji', required
        - `emoji` string, required
      - object
        - `type` 'url', required
        - `url` string, uri, required
      - object
        - `type` 'app', required
    - `createdAt` string, date-time, required
    - `lastUpdatedAt` string, date-time, required

## Other responses

- `400`: Invalid configuration
- `403`: Permission denied
- `404`: Not found or runtime pools disabled

## Changes

- **2026-10-29** `305e33634408`: 3 warning
  - added the new `fx` enum value to the `agent/credStatus/oneOf[#/components/schemas/AgentCredStatus]/latestModel/harnessProvider` response property for the response status `200`
  - added the new `fx` enum value to the `agent/harnessProvider` response property for the response status `200`
  - added the new `fx` enum value to the `agent/provider` response property for the response status `200`
- **2026-10-28** `46d4b65d9869`: 1 info
  - added the optional property `agent/slackIcon` to the response with the `200` status
- **2026-10-25** `0530fa7ea739`: 2 info
  - added the optional property `agent/credStatus/oneOf[#/components/schemas/AgentCredStatus]/liveTest/keys` to the response with the `200` status
  - added the optional property `agent/credStatus/oneOf[#/components/schemas/AgentCredStatus]/liveTest/warning` to the response with the `200` status
- **2026-10-19** `cd1cbfa2f2d5`: 1 info
  - added the optional property `agent/credStatus/oneOf[#/components/schemas/AgentCredStatus]/opencodeGo` to the response with the `200` status
- **2026-10-12** `2d005144fe35`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/agents/:id/runtime-pool/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.dev/desplega-ai/apis/agent-swarm-api/revisions/7e4c7198192a?raw)