Nous.Teams.Comms (nous v0.16.2)

PubSub topic helpers and communication utilities for multi-agent teams.

Provides consistent topic naming conventions and convenience wrappers around Nous.PubSub for team-scoped messaging.

Topic Structure

nous:team:<team_id>              — team-wide broadcasts
nous:team:<team_id>:context      — shared context updates
nous:team:<team_id>:agent:<name> — direct agent messages

Quick Start

# Subscribe an agent to team + direct topics
Comms.subscribe_team(pubsub, "team_1")
Comms.subscribe_agent(pubsub, "team_1", "alice")

# Broadcast to all agents on a team
Comms.broadcast_team(pubsub, "team_1", {:discovery, %{topic: "bug found"}})

# Send a direct message to one agent
Comms.send_to_agent(pubsub, "team_1", "bob", {:peer_message, "alice", "check this"})

Summary

Functions

agent_topic(team_id, agent_name)

Build the direct message topic for a specific agent in a team.

broadcast_team(pubsub, team_id, message)

Broadcast a message to all agents on the team.

context_topic(team_id)

Build the shared context update topic for a team.

send_to_agent(pubsub, team_id, agent_name, message)

Send a direct message to a specific agent on the team.

subscribe_agent(pubsub, team_id, agent_name)

Subscribe the calling process to a specific agent's direct message topic.

subscribe_team(pubsub, team_id)

Subscribe the calling process to the team-wide broadcast topic.

team_topic(team_id)

Build the team-wide broadcast topic.

Functions

agent_topic(team_id, agent_name)

@spec agent_topic(String.t(), String.t()) :: String.t()

Build the direct message topic for a specific agent in a team.

Examples

iex> Nous.Teams.Comms.agent_topic("team_1", "alice")
"nous:team:team_1:agent:alice"

broadcast_team(pubsub, team_id, message)

@spec broadcast_team(module() | nil, String.t(), term()) :: :ok | {:error, term()}

Broadcast a message to all agents on the team.

Options

Uses Nous.PubSub.broadcast/3 — no-op if PubSub is nil or unavailable.

context_topic(team_id)

@spec context_topic(String.t()) :: String.t()

Build the shared context update topic for a team.

Examples

iex> Nous.Teams.Comms.context_topic("team_1")
"nous:team:team_1:context"

send_to_agent(pubsub, team_id, agent_name, message)

@spec send_to_agent(module() | nil, String.t(), String.t(), term()) ::
  :ok | {:error, term()}

Send a direct message to a specific agent on the team.

Options

Uses Nous.PubSub.broadcast/3 on the agent's direct topic — no-op if PubSub is nil or unavailable.

subscribe_agent(pubsub, team_id, agent_name)

@spec subscribe_agent(module() | nil, String.t(), String.t()) ::
  :ok | {:error, term()}

Subscribe the calling process to a specific agent's direct message topic.

Options

Uses Nous.PubSub.subscribe/2 — no-op if PubSub is nil or unavailable.

subscribe_team(pubsub, team_id)

@spec subscribe_team(module() | nil, String.t()) :: :ok | {:error, term()}

Subscribe the calling process to the team-wide broadcast topic.

Options

Uses Nous.PubSub.subscribe/2 — no-op if PubSub is nil or unavailable.

team_topic(team_id)

@spec team_topic(String.t()) :: String.t()

Build the team-wide broadcast topic.

Examples

iex> Nous.Teams.Comms.team_topic("team_1")
"nous:team:team_1"