Skip to content
Ishvana Ishvana Docs

Get communication system statistics

GET
/api/agent-communication/communications/stats

Get comprehensive communication system statistics.

Retrieves system-wide metrics about inter-agent communications. All fields are populated from the AgentCommunicationHub’s live in-memory tracking:

  • total_messages: length of the hub’s bounded message_history.
  • active_consultations: the hub’s pending_consultations map.
  • completed_handoffs: count of MessageType.HANDOFF messages the hub has successfully routed through message_history.
  • failed_communications: the hub’s _failed_message_count counter (incremented on permission denial and exceptions during send).
  • average_response_time_ms: mean of the per-agent AgentMetrics.avg_response_time, averaged across agents that have at least one recorded response-time sample.
  • agent_communication_matrix: sender→recipient edge counts folded from the hub’s top_communication_patterns list.

Returns: CommunicationStatsResponse: Communication statistics and metrics.

Raises: HTTPException(500): Unexpected failure while collecting stats.

Example Response: { “totalMessages”: 1542, “activeConsultations”: 5, “completedHandoffs”: 23, “failedCommunications”: 2, “averageResponseTimeMs”: 145.3, “agentCommunicationMatrix”: { “HAWKEN”: {“LAGAN”: 45, “ORCHESTRATOR”: 23}, “LAGAN”: {“HAWKEN”: 45} } }

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

CommunicationStatsResponse

Communication statistics response model.

Provides comprehensive statistics about inter-agent communications including message counts, active conversations, consultation metrics, and system health. Used for communication monitoring and analytics.

Fields:

  • total_messages: Total messages sent through system (non-negative integer)
  • active_consultations: Currently active consultation requests (non-negative integer)
  • completed_handoffs: Successfully completed handoffs (non-negative integer)
  • failed_communications: Failed communication attempts (non-negative integer)
  • average_response_time_ms: Average agent response time in milliseconds (non-negative float)
  • agent_communication_matrix: Matrix of agent-to-agent communication counts

Usage: GET /api/agent-communication/communications/stats returns this response model.

JSON Example:

{
  "totalMessages": 1542,
  "activeConsultations": 5,
  "completedHandoffs": 23,
  "failedCommunications": 2,
  "averageResponseTimeMs": 145.3,
  "agentCommunicationMatrix": {
    "HAWKEN": {"LAGAN": 45, "ORCHESTRATOR": 23},
    "LAGAN": {"HAWKEN": 45}
  }
}
object
totalMessages
required
Totalmessages

Total messages sent through system

integer
activeConsultations
required
Activeconsultations

Currently active consultation requests

integer
completedHandoffs
required
Completedhandoffs

Successfully completed handoffs

integer
failedCommunications
required
Failedcommunications

Failed communication attempts

integer
averageResponseTimeMs
required
Averageresponsetimems

Average agent response time in ms

number
agentCommunicationMatrix
required
Agentcommunicationmatrix

Matrix of agent-to-agent communication counts

object
key
additional properties
object
key
additional properties
integer