View Source SwarmEx (SwarmEx v0.2.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
  • Network state management
  • Error handling and recovery

Example

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

# Define a tool as a regular module with functions
defmodule ClassifyTool do
  def classify(text) do
    # Perform classification
    {:ok, result}
  end
end

# Define an agent that uses the tool
defmodule MyAgent do
  use SwarmEx.Agent

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

  def handle_message(msg, state) do
    case ClassifyTool.classify(msg) do
      {:ok, result} -> {:ok, result, state}
      error -> error
    end
  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
  • :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
This function is deprecated. Tools should be implemented as regular modules with functions instead of using the Tool API.
@spec register_tool(
  module(),
  keyword()
) :: :ok | {:error, term()}

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

This function is deprecated. Instead of using the Tool API, define your tools as regular modules with functions. See the module documentation for examples.

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.