# `BeamAgent.Agents`
[🔗](https://github.com/beardedeagle/beam-agent/blob/main/lib/beam_agent/agents.ex#L1)

Agent type management for the BeamAgent SDK.

This module provides global agent type registration -- listing, registering,
unregistering, and querying agent types that are shared across all sessions.
Mutations notify the reload bus so live sessions react without restart.

## When to use directly vs through `BeamAgent`

Most callers interact with agent types through `BeamAgent`. Use this module
directly when you need focused access to agent type operations -- for example,
in an agent type management UI, an agent catalog browser, or a configuration
tool that bulk-enables/disables agent types.

## Quick example

```elixir
# Register an agent type:
:ok = BeamAgent.Agents.register("code-reviewer", %{
  name: "Code Reviewer",
  description: "Reviews code for quality issues",
  role: "reviewer",
  enabled: true
})

# List all agent types:
agents = BeamAgent.Agents.list()
for a <- agents, do: IO.puts(a.name)

# Unregister:
:ok = BeamAgent.Agents.unregister("code-reviewer")
```

## Architecture deep dive

This module is a thin Elixir facade that delegates every call to the
`:beam_agent_catalog` Erlang module's global registry functions. Zero
business logic, zero state, zero processes live here -- the Erlang module
owns the implementation. The underlying agent type data is stored in the
unified ETS table managed by `:beam_agent_registry`.

See also: `BeamAgent`, `BeamAgent.Catalog`, `BeamAgent.Plugins`.

# `agent_def`

```elixir
@type agent_def() :: %{
  :id =&gt; binary(),
  :name =&gt; binary(),
  :kind =&gt; :agent | :plugin | :slash,
  :enabled =&gt; boolean(),
  optional(:description) =&gt; binary(),
  optional(:role) =&gt; atom(),
  optional(:version) =&gt; binary(),
  optional(:config) =&gt; map()
}
```

An agent type definition stored in the global registry.

# `clear`

```elixir
@spec clear() :: :ok
```

Remove all registered agent types.

# `ensure_table`

```elixir
@spec ensure_table() :: :ok
```

Create the global registry ETS table. Idempotent.

# `get`

```elixir
@spec get(binary()) :: {:ok, agent_def()} | {:error, :not_found}
```

Fetch a single agent type by id.

# `list`

```elixir
@spec list() :: [agent_def()]
```

List all registered agent types.

# `register`

```elixir
@spec register(binary(), map()) :: :ok
```

Register an agent type globally (shared across all sessions).

## Parameters

- `id` -- unique binary identifier for the agent type.
- `opts` -- map of agent options (`:name`, `:description`, `:role`, `:enabled`, `:config`).

# `unregister`

```elixir
@spec unregister(binary()) :: :ok
```

Unregister an agent type by id. Idempotent.

---

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