Interface IAgentCommunicationBus

Interface for the AgentOS Agent Communication Bus.

The Communication Bus enables structured messaging between agents within an agency, supporting various communication patterns:

  • Point-to-Point: Direct messages between two agents
  • Broadcast: Messages to all agents in an agency
  • Request-Response: Synchronous-style communication
  • Pub/Sub: Topic-based messaging
  • Handoff: Structured task transfer between agents

Example

// Initialize bus
const bus = new AgentCommunicationBus({ logger, routingConfig });

// Agent subscribes to messages
bus.subscribe('analyst-gmi', async (msg) => {
  if (msg.type === 'task_delegation') {
    const result = await analyzeData(msg.content);
    await bus.sendToAgent(msg.fromAgentId, {
      type: 'answer',
      content: result,
      inReplyTo: msg.messageId,
    });
  }
});

// Coordinator delegates task
await bus.sendToAgent('analyst-gmi', {
  type: 'task_delegation',
  content: { data: [...], instructions: 'Analyze trends' },
  priority: 'high',
});
interface IAgentCommunicationBus {
    sendToAgent(targetAgentId, message): Promise<DeliveryStatus>;
    sendToRole(agencyId, targetRoleId, message): Promise<DeliveryStatus>;
    broadcast(agencyId, message): Promise<DeliveryStatus[]>;
    broadcastToRoles(agencyId, roleIds, message): Promise<DeliveryStatus[]>;
    requestResponse(targetAgentId, request): Promise<AgentResponse>;
    handoff(fromAgentId, toAgentId, context): Promise<HandoffResult>;
    subscribe(agentId, handler, options?): Unsubscribe;
    unsubscribeAll(agentId): void;
    createTopic(topic): Promise<MessageTopic>;
    publishToTopic(topicId, message): Promise<DeliveryStatus[]>;
    subscribeToTopic(agentId, topicId, handler): Unsubscribe;
    getDeliveryStatus(messageId): Promise<null | DeliveryStatus>;
    acknowledgeMessage(messageId, agentId): Promise<void>;
    retryDelivery(messageId): Promise<DeliveryStatus>;
    getStatistics(): BusStatistics;
    getMessageHistory(agentId, options?): Promise<AgentMessage[]>;
}

Implemented by

Methods

sendToAgent sendToRole broadcast broadcastToRoles requestResponse handoff subscribe unsubscribeAll createTopic publishToTopic subscribeToTopic getDeliveryStatus acknowledgeMessage retryDelivery getStatistics getMessageHistory

Methods

sendToAgent

  • sendToAgent(targetAgentId, message): Promise<DeliveryStatus>

  • Sends a message to a specific agent.

    Parameters

    • targetAgentId: string

      Target agent identifier

    • message: Omit<AgentMessage, "messageId" | "toAgentId" | "sentAt">

      Message to send (without routing fields)

    Returns Promise<DeliveryStatus>

    Delivery status

    Example

    await bus.sendToAgent('researcher-gmi', {
      type: 'question',
      content: 'What did you find about topic X?',
      priority: 'normal',
    });

sendToRole

  • sendToRole(agencyId, targetRoleId, message): Promise<DeliveryStatus>

  • Sends a message to an agent by role. If multiple agents have the role, uses load balancing.

    Parameters

    • agencyId: string

      Agency context

    • targetRoleId: string

      Target role identifier

    • message: Omit<AgentMessage, "messageId" | "sentAt" | "toRoleId">

      Message to send

    Returns Promise<DeliveryStatus>

    Delivery status

broadcast

  • broadcast(agencyId, message): Promise<DeliveryStatus[]>

  • Broadcasts a message to all agents in an agency.

    Parameters

    • agencyId: string

      Target agency

    • message: Omit<AgentMessage, "messageId" | "toAgentId" | "sentAt">

      Message to broadcast

    Returns Promise<DeliveryStatus[]>

    Array of delivery statuses

    Example

    await bus.broadcast('agency-123', {
      type: 'broadcast',
      content: 'Meeting in 5 minutes',
      priority: 'high',
    });

broadcastToRoles

  • broadcastToRoles(agencyId, roleIds, message): Promise<DeliveryStatus[]>

  • Broadcasts to specific roles within an agency.

    Parameters

    • agencyId: string

      Target agency

    • roleIds: string[]

      Target roles

    • message: Omit<AgentMessage, "messageId" | "sentAt">

      Message to broadcast

    Returns Promise<DeliveryStatus[]>

    Array of delivery statuses

requestResponse

  • requestResponse(targetAgentId, request): Promise<AgentResponse>

  • Sends a request and waits for a response. Implements request-response pattern over async messaging.

    Parameters

    • targetAgentId: string

      Target agent

    • request: AgentRequest

      Request message

    Returns Promise<AgentResponse>

    Response from target agent

    Example

    const response = await bus.requestResponse('expert-gmi', {
      type: 'question',
      content: 'What is the optimal approach?',
      fromAgentId: 'coordinator-gmi',
      timeoutMs: 30000,
    });
    if (response.status === 'success') {
      console.log('Answer:', response.content);
    }

handoff

  • handoff(fromAgentId, toAgentId, context): Promise<HandoffResult>

  • Initiates a structured handoff between agents. Used for transferring task ownership with full context.

    Parameters

    • fromAgentId: string

      Current owner

    • toAgentId: string

      New owner

    • context: HandoffContext

      Handoff context

    Returns Promise<HandoffResult>

    Handoff result

    Example

    const result = await bus.handoff('analyst-gmi', 'reviewer-gmi', {
      taskId: 'analysis-task-1',
      taskDescription: 'Data analysis for Q4 report',
      progress: 0.8,
      completedWork: ['Data collection', 'Initial analysis'],
      remainingWork: ['Final review', 'Report generation'],
      context: { findings: [...] },
      reason: 'completion',
    });

subscribe

  • subscribe(agentId, handler, options?): Unsubscribe

  • Subscribes an agent to receive messages.

    Parameters

    • agentId: string

      Agent to subscribe

    • handler: MessageHandler

      Message handler function

    • Optional options: SubscriptionOptions

      Subscription filter options

    Returns Unsubscribe

    Unsubscribe function

    Example

    const unsub = bus.subscribe('worker-gmi', async (msg) => {
      console.log('Received:', msg.type, msg.content);
    }, {
      messageTypes: ['task_delegation', 'question'],
      minPriority: 'normal',
    });

    // Later: unsub();

unsubscribeAll

createTopic

publishToTopic

  • publishToTopic(topicId, message): Promise<DeliveryStatus[]>

  • Publishes a message to a topic.

    Parameters

    • topicId: string

      Topic identifier

    • message: Omit<AgentMessage, "messageId" | "sentAt">

      Message to publish

    Returns Promise<DeliveryStatus[]>

    Delivery statuses for all subscribers

subscribeToTopic

  • subscribeToTopic(agentId, topicId, handler): Unsubscribe

  • Subscribes an agent to a topic.

    Parameters

    • agentId: string

      Agent to subscribe

    • topicId: string

      Topic identifier

    • handler: MessageHandler

      Message handler

    Returns Unsubscribe

    Unsubscribe function

getDeliveryStatus

  • getDeliveryStatus(messageId): Promise<null | DeliveryStatus>

  • Gets the delivery status of a message.

    Parameters

    • messageId: string

      Message identifier

    Returns Promise<null | DeliveryStatus>

    Delivery status or null if not found

acknowledgeMessage

  • acknowledgeMessage(messageId, agentId): Promise<void>

  • Acknowledges receipt of a message.

    Parameters

    • messageId: string

      Message to acknowledge

    • agentId: string

      Acknowledging agent

    Returns Promise<void>

retryDelivery

  • retryDelivery(messageId): Promise<DeliveryStatus>

  • Retries delivery of a failed message.

    Each call counts one retry, which the returned status carries in retryCount. Once RoutingConfig.maxRetries retries have been made, the call throws without sending.

    Parameters

    • messageId: string

      Message to retry

    Returns Promise<DeliveryStatus>

    New delivery status

getStatistics

getMessageHistory

  • getMessageHistory(agentId, options?): Promise<AgentMessage[]>

  • Gets message history for an agent.

    Parameters

    • agentId: string

      Agent identifier

    • Optional options: {
          limit?: number;
          since?: Date;
          types?: AgentMessageType[];
          direction?: "sent" | "received" | "both";
      }

      Query options

      • Optional limit?: number
      • Optional since?: Date
      • Optional types?: AgentMessageType[]
      • Optional direction?: "sent" | "received" | "both"

    Returns Promise<AgentMessage[]>

    Message history

Settings

Member Visibility

Theme

On This Page

sendToAgentsendToRolebroadcastbroadcastToRolesrequestResponsehandoffsubscribeunsubscribeAllcreateTopicpublishToTopicsubscribeToTopicgetDeliveryStatusacknowledgeMessageretryDeliverygetStatisticsgetMessageHistory