Send direct message between agents
POST /api/agent-communication/messages/send
Send a direct message from one agent to another.
Routes messages through the AgentCommunicationHub with proper validation, delivery tracking, and error handling. Supports various message types and priority levels for flexible inter-agent communication.
Args: request: SendMessageRequest containing to_agent, from_agent, message, message_type, priority, and optional context
Returns:
SendMessageResponse: Message delivery confirmation with tracking ID.
The status field is "success" when the hub accepted and
delivered the message, "failed" when delivery was rejected (e.g.
permission denied by the recipient’s authority policy).
Raises: HTTPException(400): Hub-level validation failure (empty content, etc.). HTTPException(404): Recipient agent is not registered with the hub. HTTPException(500): Unexpected internal failure while routing.
Example Request: POST /messages/send { “toAgent”: “HAWKEN”, “fromAgent”: “LAGAN”, “message”: “Please analyze this code”, “messageType”: “direct”, “priority”: “medium” }
Example Response: { “status”: “success”, “response”: {“messageId”: “msg_123”, “delivered”: true, “error”: null}, “agentId”: “HAWKEN”, “message”: “Message delivered to HAWKEN” }
Request Body required
Section titled “Request Body required ”Request model for sending messages between agents.
Sends a direct message from one agent to another through the communication hub with proper message type, priority, and content validation.
Fields: to_agent: Target agent ID to receive the message from_agent: Source agent ID sending the message (default: “system”) message: Message content (string or structured data) message_type: Type of message (direct, broadcast, consultation, etc.) priority: Message priority level (low, medium, high, urgent) context: Optional message context metadata
JSON Example: { “toAgent”: “HAWKEN”, “fromAgent”: “LAGAN”, “message”: “Please analyze this code”, “messageType”: “direct”, “priority”: “medium”, “context”: {“task_id”: “task_123”} }
Used By: - POST /api/agent-communication/messages/send - Agent messaging UI - Inter-agent communication workflows
object
Target agent ID
Source agent ID
Message content
Message type (direct, consultation, handoff, …)
Priority level (low, normal, medium, high, …)
Context information for agent messages.
Provides contextual metadata for message routing, processing, and tracking in agent communication.
Fields: task_id: Associated task identifier session_id: Session identifier conversation_id: Conversation thread ID priority: Message priority requires_response: Whether response expected timeout_ms: Response timeout metadata: Additional context metadata
Used By: - SendMessageRequest.context - ConsultationRequestRequest.context - Message routing and tracking
object
Responses
Section titled “ Responses ”Successful Response
Send message response model.
Provides message delivery confirmation and status for agent-to-agent messaging operations. Includes delivery information and target agent identification.
Fields:
status: Operation status (success or failed)response: MessageDeliveryInfo object containing delivery detailsagent_id: Target agent identifiermessage: Status message providing additional context
Usage: POST /api/agent-communication/messages/send returns this response model.
JSON Example:
{
"status": "success",
"response": {
"messageId": "msg_123",
"delivered": true,
"error": null
},
"agentId": "hawken",
"message": "Message delivered successfully"
}object
Operation status (success or failed)
Target agent identifier
Status message
Validation Error