Nous.Teams.Role (nous v0.16.1)

View Source

Role definitions for team agents.

A role configures an agent's system prompt, tool access, and iteration limits. Roles are plain structs with helper functions — no process needed.

Architecture

Roles are applied when spawning agents into a team. The system_prompt is prepended to the agent's instructions, and allowed_tools/denied_tools filter the available tool set.

Quick Start

# Use a built-in role
role = Role.researcher()

# Create a custom role
role = Role.new(name: :reviewer, system_prompt: "Review code carefully", denied_tools: ["execute_code"])

# Filter tools based on role
filtered = Role.apply_tool_filter(role, all_tools)

Summary

Types

t()

Functions

apply_tool_filter(role, tools)

Filter a list of tools based on the role's allowed/denied lists.

coder()

Default coder role.

lead()

Default lead role.

new(attrs)

Create a new role from keyword attributes.

researcher()

Default researcher role.

Types

t()

@type t() :: %Nous.Teams.Role{
  allowed_tools: [String.t()] | nil,
  denied_tools: [String.t()] | nil,
  max_iterations: pos_integer(),
  name: atom(),
  system_prompt: String.t() | nil
}

Functions

apply_tool_filter(role, tools)

@spec apply_tool_filter(t(), [Nous.Tool.t()]) :: [Nous.Tool.t()]

Filter a list of tools based on the role's allowed/denied lists.

  • If allowed_tools is set, only tools in that list are kept.
  • If denied_tools is set, tools in that list are removed.
  • If neither is set, all tools are returned.
  • allowed_tools takes precedence over denied_tools.

Examples

iex> role = Nous.Teams.Role.new(name: :restricted, allowed_tools: ["search", "read_file"])
iex> tools = [%Nous.Tool{name: "search", function: &Function.identity/1}, %Nous.Tool{name: "execute", function: &Function.identity/1}]
iex> filtered = Nous.Teams.Role.apply_tool_filter(role, tools)
iex> length(filtered)
1

coder()

@spec coder() :: t()

Default coder role.

Has access to code editing tools but restricted from destructive operations.

Examples

iex> role = Nous.Teams.Role.coder()
iex> role.name
:coder

lead()

@spec lead() :: t()

Default lead role.

Has unrestricted tool access and coordinates the team.

Examples

iex> role = Nous.Teams.Role.lead()
iex> role.name
:lead

new(attrs)

@spec new(keyword()) :: t()

Create a new role from keyword attributes.

Options

  • :name — atom identifying the role (required)
  • :system_prompt — system prompt prepended to agent instructions
  • :allowed_tools — whitelist of tool names (nil means all allowed)
  • :denied_tools — blacklist of tool names (nil means none denied)
  • :max_iterations — max agent loop iterations (default: 15)

Examples

iex> role = Nous.Teams.Role.new(name: :researcher, system_prompt: "Research topics thoroughly")
iex> role.name
:researcher

researcher()

@spec researcher() :: t()

Default researcher role.

Focused on information gathering with read-only tool access.

Examples

iex> role = Nous.Teams.Role.researcher()
iex> role.name
:researcher