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 justmodule(required):tools- list of modules implementingAlloy.Tooland/orAlloy.Tool.Inlinestructs built withAlloy.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, otherwise200_000):compaction- grouped compaction settings likereserve_tokens,keep_recent_tokens, andfallback(default: derived from:max_tokens):middleware- list ofAlloy.Middlewaremodules (default:[]):tool_validation-:requiredfor object/required-key checks (default), or:schemafor 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_tokenswhen not set explicitly (default:%{}):model_catalog- module implementingAlloy.ModelCatalog, consulted for model context windows after:model_metadata_overrides(default:Alloy.ModelMetadata):code_execution-trueenables Anthropic's server-side code execution tool; the same as settingcode_execution: truein the provider config (default:false):on_event- 1-arity function called with eachAlloy.Eventsenvelope (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_turnwithout 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
@type result() :: Alloy.Result.t()
Functions
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.
@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