BeamAgent.Agents (beam_agent_ex v0.1.0)

Copy Markdown View Source

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

# 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.

Summary

Types

agent_def()

An agent type definition stored in the global registry.

Functions

clear()

Remove all registered agent types.

ensure_table()

Create the global registry ETS table. Idempotent.

get(id)

Fetch a single agent type by id.

list()

List all registered agent types.

register(id, opts)

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

unregister(id)

Unregister an agent type by id. Idempotent.

Types

agent_def()

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

An agent type definition stored in the global registry.

Functions

clear()

@spec clear() :: :ok

Remove all registered agent types.

ensure_table()

@spec ensure_table() :: :ok

Create the global registry ETS table. Idempotent.

get(id)

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

Fetch a single agent type by id.

list()

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

List all registered agent types.

register(id, opts)

@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(id)

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

Unregister an agent type by id. Idempotent.