Agent Handoff

POST

/api/agents/handoff

• DivinityEngine - Local development
• DivinityEngine - Localhost alternative

Execute a controlled handoff between agents with context preservation.

Args: request_data: Handoff request containing source/target agents and context request: FastAPI Request object for backend service access

Returns: AgentHandoffResponse: Handoff execution status and tracking information

Note: Orchestrates seamless agent handoffs with full conversation context transfer, ensuring continuity of service and proper workflow coordination between agents for optimal user experience and task completion.

Request Body ^required

AgentHandoffRequest

Agent task handoff request model.

Represents a request to hand off an ongoing task or conversation from one agent to another more suitable agent. Includes full conversation context and handoff reasoning for seamless transitions.

Fields: from_agent: Agent initiating the handoff to_agent: Agent receiving the handoff conversation_context: Full conversation history and state handoff_reason: Explanation for why handoff is occurring priority: Handoff priority level (default: “medium”) handoff_time: Timestamp when handoff was requested

Used By: - POST /api/agents/handoff endpoint - Agent handoff workflow coordination - boot coordinator orchestrator for optimal agent selection - Handoff history and analytics tracking - Multi-agent conversation management

object

fromAgent

required

Fromagent

string

toAgent

required

Toagent

string

conversationContext

required

Conversationcontext

object

key

additional properties

Any of:

string

string

integer

integer

number

number

handoffReason

required

Handoffreason

string

priority

Priority

string

default: medium

handoffTime

Handofftime

Handoff timestamp

string format: date-time

Responses

200

Successful Response

AgentHandoffResponse

Agent handoff execution response model.

Provides handoff status, tracking identifier, and execution results for controlled agent handoffs with context preservation.

Fields:

• status: Handoff execution status (success/failed)
• handoff_id: Unique tracking identifier for handoff
• result: Handoff execution success flag
• message: Human-readable handoff status message

object

status

required

Status

Handoff execution status

string

handoffId

required

Any of:

string

string

null

null

result

required

Result

Handoff execution result (success/failure)

boolean

message

required

Message

Handoff status message

string

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