Alloy - a minimal, OTP-native AI agent engine for Elixir

striking

I’ve been building AI agents in Elixir for a while and kept running into the same frustration, every framework either locks you into one provider, ships fifteen dependencies you don’t need, or treats Elixir as a second-class citizen behind Python.

So I built Alloy. It’s a minimal agent engine — the completion → tool-call loop and nothing else. You give it a prompt, a provider, and some tools, and it runs until the job is done.

  {:ok, result} = Alloy.run(
    "Read mix.exs and tell me the version",
    provider: {Alloy.Provider.Anthropic,
      api_key: System.get_env("ANTHROPIC_API_KEY"),
      model: "claude-sonnet-4-6"},
    tools: [Alloy.Tool.Core.Read]
  )

What’s in the box:

8 providers — Anthropic, OpenAI, Google Gemini, Ollama, OpenRouter, xAI, DeepSeek, Mistral. Swap in one line, nothing else changes.
3 dependencies — jason, req, telemetry. That’s it.
GenServer agents — Alloy.Agent.Server wraps the loop in a supervised process. Stateful, long-running, message-passing.
Multi-agent teams — Alloy.Team gives you delegate, broadcast, and handoff between named agents. Each is its own supervised process — one crashes, the others keep
going.
Streaming — token-by-token from any provider, same interface.
Async dispatch — send_message/2 fires non-blocking and broadcasts the result via PubSub. Designed for Phoenix LiveView.
Middleware — plug in telemetry, logging, or custom hooks before/after completions and tool calls.
Context discovery — drop .md files in .alloy/context/ and they’re auto-injected into the system prompt.

The philosophy is close to pi-agent: what you leave out matters more than what you put in. If an agent needs a capability Alloy doesn’t ship, the agent writes the code itself.

The OTP angle is the part I’m most interested in feedback on. Agents as supervised GenServers isn’t a pattern you find in Python-based frameworks — it’s architecturally native to the BEAM, not bolted on. Fault isolation, message passing, and real concurrency (not coroutines) come for free.

{:ok, team} = Alloy.Team.start_link(
    agents: [
      researcher: [
        provider: {Alloy.Provider.Google,
          api_key: "...", model: "gemini-2.5-flash"},
        system_prompt: "You are a research assistant."
      ],
      coder: [
        provider: {Alloy.Provider.Anthropic,
          api_key: "...", model: "claude-sonnet-4-6"},
        tools: [Alloy.Tool.Core.Read, Alloy.Tool.Core.Write],
        system_prompt: "You are a senior developer."
      ]
    ]
  )

  {:ok, research} = Alloy.Team.delegate(team, :researcher,
    "Find the latest Elixir 1.18 changes")
  {:ok, _} = Alloy.Team.delegate(team, :coder,
    "Update our code based on: #{research.text}")

Available now on Hex as {:alloy, “~> 0.4”}.

https://github.com/alloy-ex/alloy

Happy to answer questions or take PRs. Particularly interested in feedback on the Team API and whether the provider behaviour interface makes contributing new providers straightforward.

Personally, I think Elixir and OTP is the ideal architecture for agentic systems.

1 comment

#agent #library #otp #genserver #ai #llm #alloy

19 1397 1

2026-04-12 21:45:56 UTC

Showing Posts 1 to 1

Show Best Posts
Show All (oldest first)
Show All (newest first)

striking

v0.10 Update

Quick update on Alloy.

Context: OpenAI recently revealed their multi-agent orchestrator (Symphony) is built on Elixir. The model itself chose it for BEAM’s supervision capabilities. Symphony coordinates fleets of agents. Alloy operates one level down, as the engine inside each individual agent. Different layer, same thesis: the BEAM is a natural fit for AI agent workloads.

3 new providers

Alloy now supports 6 providers: Anthropic, OpenAI, Gemini, xAI, Codex, and any OpenAI-compatible API (Ollama, DeepSeek, etc.). Swap with one line:

{:ok, result} = Alloy.run("Summarize this code",
  provider: {Alloy.Provider.XAI,
    api_key: System.get_env("XAI_API_KEY"),
    model: "grok-4"
  },
  tools: [Alloy.Tool.Core.Read]
)

`until_tool` for structured output

Instead of hoping the model returns valid JSON, define a tool with the exact schema you want and set until_tool: "submit_answer". The loop won’t complete until the model calls that tool. Schema validated at the API level.

{:ok, result} = Alloy.run("Analyze this data",
  provider: {Alloy.Provider.Anthropic, api_key: key, model: "claude-sonnet-4-6"},
  tools: [SubmitAnalysis],
  until_tool: "submit_analysis"
)

HITL `:edit` variant

Middleware can now return {:edit, modified_call} from :before_tool_call to rewrite tool arguments before execution. Previously you could only block or allow. Now you can correct a file path, sanitize a command, or enforce policy without stopping the agent.

def call(:before_tool_call, state) do
  call = state.config.context[:current_tool_call]
  if dangerous?(call), do: {:edit, sanitize(call)}, else: state
end

Tool safety

Tools declare concurrent?/0 (safe to parallelize?) and max_result_chars/0 (output cap). The executor handles the rest. Plus automatic recovery when context gets too long.

Numbers: 568 tests, 0 failures. About 7,500 lines of code. 3 runtime dependencies. MIT.

Full changelog: alloy/CHANGELOG.md at main · alloy-ex/alloy · GitHub

Feedback welcome, especially on the until_tool pattern. Curious how others are handling structured output from agents.

Post #1

— All posts loaded —