---
title: "Switch a logical AO session to another agent harness"
method: POST
path: "/api/v1/sessions/{sessionId}/switch-agent"
tags: ["sessions"]
---

# Switch a logical AO session to another agent harness

`POST /api/v1/sessions/{sessionId}/switch-agent`

## Path parameters

- `sessionId` string, required — Session identifier, e.g. project-1.

## Request body

- SwitchAgentRequest
  - `idempotencyKey` string — Optional retry key. Reusing it with a different request is rejected.
  - `note` string — Optional user guidance included in the bounded handoff context.
  - `targetHarness` 'claude-code' | 'codex', required — Agent harness to continue the logical AO session with.

## Response `200`

OK

- AgentSwitchResponse
  - `switch` AgentSwitch, required
    - `agentHandoffStatus` 'not_attempted' | 'requested' | 'received' | 'unavailable' | 'timed_out' | 'failed' | 'rejected', required
    - `errorCode` 'daemon_restart_pre_stop' | 'daemon_restart_post_stop' | 'daemon_restart_unrecoverable_target' | 'daemon_restart_before_delivery' | 'delivery_unconfirmed' | 'source_session_terminated' | 'source_stop_unconfirmed' | 'target_binary_missing' | 'target_agent_unauthorized' | 'target_start_unconfirmed' | 'request_cancelled' | 'source_blocked' | 'failed_pre_stop' | 'failed_post_stop' | 'target_ready_failed' | 'delivery_failed' | 'switch_failed'
    - `fromHarness` string, required
    - `id` string, required
    - `requestedAt` string, date-time, required
    - `semanticHandoffIncluded` boolean, required
    - `sessionId` string, required
    - `sourceTranscriptStatus` 'not_attempted' | 'available' | 'unavailable'
    - `state` 'preparing_handoff' | 'stopping_source' | 'source_stopped' | 'starting_target' | 'target_ready' | 'delivering_context' | 'completed' | 'failed', required
    - `targetHarness` string, required
    - `targetStartMode` 'fresh' | 'resumed'
    - `updatedAt` string, date-time, required

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `409` — Conflict
- `500` — Internal Server Error
- `501` — Not Implemented

---

[API](https://skmtc.net/composiohq/apis/agent-orchestrator-http-daemon.md) · [All operations](https://skmtc.net/composiohq/apis/agent-orchestrator-http-daemon/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/composiohq/agent-orchestrator-http-daemon/revisions/641f372d664d/schema)