Alloy (alloy v0.13.0)

Copy Markdown View Source

Model-agnostic agent harness for Elixir.

Alloy provides the minimal agent loop: send messages to any LLM, execute tool calls, loop until done. Zero framework dependencies.

Quick Start

{:ok, result} = Alloy.run("What is 2+2?",
  provider: {Alloy.Provider.Anthropic, api_key: "sk-ant-..."},
  system_prompt: "You are helpful."
)
result.text #=> "4"

With Tools

{:ok, result} = Alloy.run("Read mix.exs and tell me the version",
  provider: {Alloy.Provider.Anthropic, api_key: "sk-ant-..."},
  tools: [Alloy.Tool.Core.Read],
  max_turns: 10
)

Continuing a Conversation

{:ok, result} = Alloy.run("Now edit that file",
  provider: {Alloy.Provider.OpenAI, api_key: "sk-..."},
  tools: [Alloy.Tool.Core.Read, Alloy.Tool.Core.Edit],
  messages: previous_result.messages
)

One-Shot Streaming

{:ok, result} = Alloy.stream("Explain OTP", fn chunk ->
  IO.write(chunk)
end,
  provider: {Alloy.Provider.OpenAI, api_key: "sk-...", model: "gpt-5.4"}
)

Options

  • :provider - {module, config_keyword_list} or just module (required)
  • :tools - list of modules implementing Alloy.Tool and/or Alloy.Tool.Inline structs built with Alloy.Tool.inline/1 (default: [])
  • :system_prompt - system prompt string (default: nil)
  • :messages - existing conversation history (default: [])
  • :max_turns - maximum agent loop iterations (default: 25)
  • :max_tokens - context window budget for compaction (default: provider model window when known, otherwise 200_000)
  • :compaction - grouped compaction settings like reserve_tokens, keep_recent_tokens, and fallback (default: derived from :max_tokens)
  • :middleware - list of Alloy.Middleware modules (default: [])
  • :tool_validation - :required for object/required-key checks (default), or :schema for optional JSON Schema validation
  • :tool_concurrency - positive integer limiting parallel tool execution (default: scheduler count)
  • :stop_after_tool - complete successfully after this tool succeeds; settle the whole round and return its output (default: nil)
  • :working_directory - base path for file tools (default: ".")
  • :context - arbitrary map passed to tools and middleware (default: %{})
  • :model_metadata_overrides - overrides for model context windows used to derive :max_tokens when not set explicitly (default: %{})
  • :model_catalog - module implementing Alloy.ModelCatalog, consulted for model context windows after :model_metadata_overrides (default: Alloy.ModelMetadata)
  • :code_execution - true enables Anthropic's server-side code execution tool; the same as setting code_execution: true in the provider config (default: false)
  • :on_event - 1-arity function called with each Alloy.Events envelope (tool events, plus text and thinking deltas when streaming) (default: nil)
  • :until_tool - tool name (string) that must be called successfully before the loop completes. If the model signals :end_turn without a call to this tool that succeeded (a failed, blocked or unknown call does not count), the loop continues with a prompt to call it. Useful for structured output enforcement. (default: nil)

Budget limits

Price the accumulated usage yourself in :before_completion middleware, which runs before every provider request, and halt when the run reaches its limit:

defmodule MyApp.BudgetGuard do
  @behaviour Alloy.Middleware

  # USD per million tokens for the model you run.
  @input_per_m 3.0
  @output_per_m 15.0

  @impl true
  def call(:before_completion, state) do
    limit = Map.fetch!(state.config.context, :max_budget_cents)
    usage = Alloy.Usage.estimate_cost(state.usage, @input_per_m, @output_per_m)

    if usage.estimated_cost_cents >= limit do
      {:halt, "budget of #{limit} cents reached"}
    else
      state
    end
  end

  def call(_hook, state), do: state
end

Alloy.run(prompt,
  provider: provider,
  middleware: [MyApp.BudgetGuard],
  context: %{max_budget_cents: 50}
)

A halted run returns {:error, result} with status: :halted and error: "Halted by middleware: budget of 50 cents reached". Alloy.Usage.estimate_cost/3 prices input and output tokens only; add your provider's cache read and write prices if you use prompt caching.

Summary

Functions

Run the agent loop with a message and options.

Run the agent loop and stream text deltas as they arrive.

Types

result()

@type result() :: Alloy.Result.t()

Functions

run(message \\ nil, opts)

@spec run(String.t() | nil, keyword()) :: {:ok, result()} | {:error, result()}

Run the agent loop with a message and options.

The first argument can be a string (converted to a user message) or ignored if :messages option provides conversation history.

Accepts :on_event like stream/3. Without streaming, the callback receives the tool events (:tool_start, :tool_end) but no text deltas.

Returns {:ok, result} on completion or {:error, result} on failure.

stream(message, on_chunk, opts \\ [])

@spec stream(String.t() | nil, (String.t() -> any()), keyword()) ::
  {:ok, result()} | {:error, result()}

Run the agent loop and stream text deltas as they arrive.

It returns the same result shape as run/2.

The first argument can be a string (converted to a user message) or nil if the :messages option provides conversation history.

Options

Accepts the same options as run/2, plus:

  • :on_event - function called with normalized event envelopes during the run