Skip to content
Ishvana Ishvana Docs

Initiate task handoff between agents

POST
/api/agent-communication/handoffs/initiate

Initiate a task handoff from one agent to another.

Transfers an ongoing task or conversation with full context preservation. Ensures smooth transitions with proper state transfer and handoff tracking.

Args: request: HandoffInitiateRequest containing from_agent, to_agent, task_context, and handoff_reason

Returns: HandoffInitiateResponse: Handoff confirmation with tracking ID. accepted reflects whether the underlying handoff message was successfully queued on the receiving agent; status is "accepted" when queued, "failed" otherwise.

Raises: HTTPException(400): Hub-level validation failure (empty content, etc.). HTTPException(404): Target agent is not registered with the hub. HTTPException(500): Unexpected internal failure while routing.

Example Request: POST /handoffs/initiate { “fromAgent”: “LAGAN”, “toAgent”: “HAWKEN”, “taskContext”: {“task_id”: “task_456”, “status”: “in_progress”}, “handoffReason”: “Requires code expertise” }

Example Response: { “status”: “accepted”, “handoffId”: “handoff_abc123def456”, “accepted”: true, “timestamp”: “2026-04-19T10:30:00+00:00” }

Request Body required

Section titled “Request Body required ”
HandoffInitiateRequest

Request model for initiating agent handoff.

Transfers an ongoing task or conversation from one agent to another with full context preservation and handoff reasoning.

Fields: from_agent: Agent initiating the handoff to_agent: Agent receiving the handoff task_context: Complete task state and history handoff_reason: Reason for the handoff priority: Handoff priority level

JSON Example: { “fromAgent”: “LAGAN”, “toAgent”: “HAWKEN”, “taskContext”: {“task_id”: “task_456”, “status”: “in_progress”}, “handoffReason”: “Requires creative expertise”, “priority”: “high” }

Used By: - POST /api/agent-communication/handoffs/initiate - Agent handoff workflows - Task routing system

object
fromAgent
required
Fromagent

Source agent ID

string
>= 1 characters
toAgent
required
Toagent

Target agent ID

string
>= 1 characters
taskContext
required
TaskContextInfo

Task context and state

object
taskId
Any of:
string
taskType
Any of:
string
currentStatus
Any of:
string
progressPercent
Any of:
number
<= 100
history
Any of:
Array<string>
artifacts
Any of:
Array<string>
metadata
Any of:
object
key
additional properties
string
handoffReason
required
Handoffreason

Handoff reasoning

string
>= 1 characters
priority
Priority

Handoff priority

string
default: medium
Allowed values: low normal medium high critical urgent

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

HandoffInitiateResponse

Handoff initiation response model.

Provides confirmation and tracking information for agent handoff operations. Includes handoff ID, acceptance status, and timestamp.

Fields:

  • status: Operation status (success/error)
  • handoff_id: Unique handoff identifier for tracking
  • accepted: Boolean indicating whether handoff was accepted
  • timestamp: ISO 8601 timestamp of handoff initiation

Usage: POST /api/agent-communication/handoffs/initiate returns this response model.

JSON Example:

{
  "status": "success",
  "handoffId": "handoff_123",
  "accepted": true,
  "timestamp": "2025-01-31T10:30:00Z"
}
object
status
required
Status

Operation status

string
handoffId
required
Handoffid

Unique handoff identifier

string
accepted
required
Accepted

Whether handoff was accepted

boolean
timestamp
required
Timestamp

ISO timestamp of handoff initiation

string

422

Section titled “422 ”

Validation Error

HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object