View Source SwarmEx (SwarmEx v0.1.0)

SwarmEx is an Elixir library for lightweight, controllable, and testable AI agent orchestration.

It provides a simple API for creating and managing networks of AI agents, with features including:

  • Agent lifecycle management
  • Message routing between agents
  • Tool integration and execution
  • Network state management
  • Error handling and recovery

Example

# Create a new agent network
{:ok, network} = SwarmEx.create_network()

# Define an agent
defmodule MyAgent do
  use SwarmEx.Agent

  def init(opts), do: {:ok, opts}

  def handle_message(msg, state) do
    {:ok, "Echo: #{msg}", state}
  end

  def handle_tool(:example, args, state) do
    {:ok, args, state}
  end
end

# Add an agent to the network
{:ok, agent_pid} = SwarmEx.create_agent(network, MyAgent)

# Send a message to the agent
{:ok, response} = SwarmEx.send_message(agent_pid, "Hello!")

Summary

Functions

Creates a new agent in the given network.

Creates a new agent network with the given configuration.

Lists all active agents in a network.

Registers a new tool that can be used by agents in the network.

Sends a message to an agent identified by ID within a network and waits for the response.

Sends a message to an agent identified by PID and waits for the response.

Stops an agent and removes it from its network.

Updates the shared context for a network of agents.

Returns the version of the SwarmEx library.

Types

@type agent() :: pid() | String.t()
@type message() :: term()
@type network() :: pid()
@type response() :: {:ok, term()} | {:error, term()}

Functions

Link to this function

create_agent(network, agent_module, opts \\ [])

View Source
@spec create_agent(network(), module(), keyword()) ::
  {:ok, agent()} | {:error, term()}

Creates a new agent in the given network.

Options

  • :name - Optional name for the agent
  • :tools - List of tools available to the agent
  • :instruction - Base instruction/prompt for the agent
  • All other options are passed to the agent's init/1 callback

Examples

{:ok, agent} = SwarmEx.create_agent(network, MyAgent)
{:ok, agent} = SwarmEx.create_agent(network, MyAgent, name: "processor")
Link to this function

create_network(opts \\ [])

View Source
@spec create_network(keyword()) :: {:ok, network()} | {:error, term()}

Creates a new agent network with the given configuration.

Options

  • :name - Optional name for the network
  • :context - Initial context map (default: %{})
  • All other options are passed to the underlying Client

Examples

{:ok, network} = SwarmEx.create_network()
{:ok, named_network} = SwarmEx.create_network(name: "primary_network")
@spec list_agents(network()) :: {:ok, [String.t()]} | {:error, term()}

Lists all active agents in a network.

Examples

{:ok, agent_ids} = SwarmEx.list_agents(network)
Link to this function

register_tool(tool_module, opts \\ [])

View Source
@spec register_tool(
  module(),
  keyword()
) :: :ok | {:error, term()}

Registers a new tool that can be used by agents in the network.

Examples

SwarmEx.register_tool(MyTool, max_retries: 3)
Link to this function

send_message(network, agent_id, message)

View Source
@spec send_message(network(), String.t(), message()) :: response()

Sends a message to an agent identified by ID within a network and waits for the response.

Examples

{:ok, response} = SwarmEx.send_message(network, "agent_id", "Process this")
Link to this function

send_message_to_pid(agent_pid, message)

View Source
@spec send_message_to_pid(pid(), message()) :: response()

Sends a message to an agent identified by PID and waits for the response.

Examples

{:ok, response} = SwarmEx.send_message_to_pid(agent_pid, "Process this")
Link to this function

stop_agent(agent, reason \\ :normal)

View Source
@spec stop_agent(agent(), term()) :: :ok | {:error, term()}

Stops an agent and removes it from its network.

Examples

:ok = SwarmEx.stop_agent(agent)
:ok = SwarmEx.stop_agent(agent, :shutdown)
Link to this function

update_context(network, context)

View Source
@spec update_context(network(), map()) :: :ok | {:error, term()}

Updates the shared context for a network of agents.

Examples

:ok = SwarmEx.update_context(network, %{key: "value"})
@spec version() :: String.t()

Returns the version of the SwarmEx library.