Nous.Teams (nous v0.15.5)

Top-level API for multi-agent team orchestration.

Provides functions to create teams, spawn agents within teams, communicate between agents, and dissolve teams. Each team gets its own supervision tree with a Coordinator, SharedState, optional RateLimiter, and a DynamicSupervisor for agent processes.

Architecture

Nous.AgentDynamicSupervisor
└── Nous.Teams.Supervisor (per team)
    ├── Nous.Teams.Coordinator
    ├── Nous.Teams.SharedState
    ├── Nous.Teams.RateLimiter (optional)
    └── DynamicSupervisor (agents)

Quick Start

# Create a team
{:ok, team_id} = Nous.Teams.create(name: "Research Team", pubsub: MyApp.PubSub)

# Spawn agents
{:ok, _pid} = Nous.Teams.spawn_agent(team_id, "alice", %{
  model: "openai:gpt-4",
  instructions: "Research specialist"
}, role: Nous.Teams.Role.researcher())

{:ok, _pid} = Nous.Teams.spawn_agent(team_id, "bob", %{
  model: "openai:gpt-4",
  instructions: "Code specialist"
}, role: Nous.Teams.Role.coder())

# Check status
Nous.Teams.team_status(team_id)

# Communicate
Nous.Teams.send_message(team_id, "alice", {:user_message, "Start researching"})

# Dissolve when done
Nous.Teams.dissolve(team_id)

Summary

Functions

broadcast(team_id, message)

Broadcast a message to all agents in a team.

create(opts \\ [])

Create a new team.

dissolve(team_id)

Dissolve a team, stopping all agents and cleaning up.

list_agents(team_id)

List all agents in a team.

send_message(team_id, agent_name, message)

Send a message to a specific agent in a team.

spawn_agent(team_id, agent_name, agent_config, opts \\ [])

Spawn an agent within an existing team.

team_status(team_id)

Get the current status of a team.

Functions

broadcast(team_id, message)

@spec broadcast(String.t(), term()) :: :ok | {:error, term()}

Broadcast a message to all agents in a team.

Examples

Nous.Teams.broadcast(team_id, {:announcement, "New task available"})

create(opts \\ [])

@spec create(keyword()) :: {:ok, String.t()} | {:error, term()}

Create a new team.

Starts a Nous.Teams.Supervisor under Nous.AgentDynamicSupervisor with the given options. Returns {:ok, team_id}.

Options

:name — human-readable team name (default: auto-generated)
:team_id — explicit team ID (default: auto-generated)
:pubsub — PubSub module (default: configured PubSub)
:budget — team budget in USD (enables RateLimiter)
:per_agent_budget — per-agent budget in USD
:rpm — requests per minute limit
:tpm — tokens per minute limit

Examples

{:ok, team_id} = Nous.Teams.create(name: "Research Team")
{:ok, team_id} = Nous.Teams.create(name: "Budget Team", budget: 10.0)

dissolve(team_id)

@spec dissolve(String.t()) :: :ok | {:error, term()}

Dissolve a team, stopping all agents and cleaning up.

Examples

:ok = Nous.Teams.dissolve(team_id)

list_agents(team_id)

@spec list_agents(String.t()) :: [map()] | {:error, term()}

List all agents in a team.

Examples

agents = Nous.Teams.list_agents(team_id)
# [%{name: "alice", pid: #PID<0.123.0>, status: :running}]

send_message(team_id, agent_name, message)

@spec send_message(String.t(), String.t(), term()) :: :ok | {:error, term()}

Send a message to a specific agent in a team.

Examples

Nous.Teams.send_message(team_id, "alice", {:user_message, "Start research"})

spawn_agent(team_id, agent_name, agent_config, opts \\ [])

@spec spawn_agent(String.t(), String.t(), map(), keyword()) ::
  {:ok, pid()} | {:error, term()}

Spawn an agent within an existing team.

Options

:role — a Nous.Teams.Role struct to apply
:plugins — list of plugin modules

Examples

{:ok, pid} = Nous.Teams.spawn_agent(team_id, "alice", %{
  model: "openai:gpt-4",
  instructions: "Research specialist"
})

team_status(team_id)

@spec team_status(String.t()) :: map() | {:error, term()}

Get the current status of a team.

Examples

status = Nous.Teams.team_status(team_id)
# %{team_id: "...", team_name: "...", agent_count: 2, agents: [...]}