LemonAgent.AgentRegistry (lemon_agent v0.1.0)

Registry for agent process lookup and discovery.

This module provides a wrapper around Elixir's Registry for tracking agent processes. Agents are registered with structured keys for easy lookup and enumeration.

Key Format

Keys are tuples of the form {session_id, role, index} where:

session_id - The parent session ID
role - The agent role (e.g., :main, :research, :implement)
index - An index for multiple agents of the same role (0-based)

Examples

# Register an agent
LemonAgent.AgentRegistry.register({session_id, :research, 0})

# Look up an agent
{:ok, pid} = LemonAgent.AgentRegistry.lookup({session_id, :research, 0})

# List all agents for a session
agents = LemonAgent.AgentRegistry.list_by_session(session_id)

Summary

Types

key()

Functions

count()

Count the number of registered agents.

count_by_session(session_id)

Count agents for a specific session.

list()

List all registered keys and their PIDs.

list_by_role(role)

List all agents with a specific role across all sessions.

list_by_session(session_id)

List all agents for a specific session.

lookup(key)

Look up a process by its key.

lookup_with_metadata(key)

Look up a process and its metadata by key.

registry_name()

Get the registry name for use in via tuples.

unregister(key)

Unregister the current process from the given key.

via(key)

Returns a via tuple for registering a process with this registry.

Types

key()

@type key() :: {session_id :: String.t(), role :: atom(), index :: non_neg_integer()}

Functions

count()

@spec count() :: non_neg_integer()

Count the number of registered agents.

count_by_session(session_id)

@spec count_by_session(String.t()) :: non_neg_integer()

Count agents for a specific session.

list()

@spec list() :: [{key(), pid()}]

List all registered keys and their PIDs.

Examples

[{{session_id, :main, 0}, pid1}, {{session_id, :research, 0}, pid2}] = AgentRegistry.list()

list_by_role(role)

@spec list_by_role(atom()) :: [{String.t(), non_neg_integer(), pid()}]

List all agents with a specific role across all sessions.

Returns a list of {session_id, index, pid} tuples.

Examples

[{session1, 0, pid1}, {session2, 0, pid2}] = AgentRegistry.list_by_role(:research)

list_by_session(session_id)

@spec list_by_session(String.t()) :: [{atom(), non_neg_integer(), pid()}]

List all agents for a specific session.

Returns a list of {role, index, pid} tuples for all agents belonging to the given session.

Examples

[{:main, 0, pid1}, {:research, 0, pid2}] = AgentRegistry.list_by_session(session_id)

lookup(key)

@spec lookup(key()) :: {:ok, pid()} | :error

Look up a process by its key.

Returns {:ok, pid} if found, or :error if not registered.

Examples

{:ok, pid} = AgentRegistry.lookup({session_id, :research, 0})

lookup_with_metadata(key)

@spec lookup_with_metadata(key()) :: {:ok, pid(), term()} | :error

Look up a process and its metadata by key.

Returns {:ok, pid, metadata} if found, or :error if not registered.

Examples

{:ok, pid, %{model: "claude-3"}} = AgentRegistry.lookup_with_metadata({session_id, :research, 0})

register(key)

@spec register(key()) :: :ok | {:error, {:already_registered, pid()}}

Returns :ok on success or {:error, {:already_registered, pid}} if another process is already registered with this key.

Examples

:ok = AgentRegistry.register({session_id, :research, 0})

register(key, metadata)

@spec register(key(), term()) :: :ok | {:error, {:already_registered, pid()}}

The metadata can be any term and is stored alongside the registration.

Examples

:ok = AgentRegistry.register({session_id, :research, 0}, %{model: "claude-3"})

registry_name()

@spec registry_name() :: atom()

Get the registry name for use in via tuples.

unregister(key)

@spec unregister(key()) :: :ok

Unregister the current process from the given key.

Examples

:ok = AgentRegistry.unregister({session_id, :research, 0})

via(key)

@spec via(key()) :: {:via, Registry, {atom(), key()}}

Returns a via tuple for registering a process with this registry.

Examples

GenServer.start_link(MyAgent, args, name: AgentRegistry.via({session_id, :main, 0}))