# `Nous.Teams.Role`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/teams/role.ex#L1)

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)

# `t`

```elixir
@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
}
```

# `apply_tool_filter`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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

---

*Consult [api-reference.md](api-reference.md) for complete listing*