API Reference — Elixir

Package toolnexus (Hex), Elixir ≥ 1.16 / OTP 26. See the combined API Reference for every symbol shown in eight-language synced tabs.

Why the BEAM port exists

Long-running agents want supervision, isolation, and cheap concurrency — and that is exactly what agent orchestration needs. The Elixir/OTP port is where sub-agents, teams, hierarchical budgets, and durable suspension feel native (every MCP connection is a supervised process; a crashed stdio server is isolated as "failed" without taking the toolkit down; parallel tool calls ride Task.async_stream). Proving that shape on the BEAM is the reason toolnexus carries agentic orchestration across all eight languages — same contract everywhere, native OTP underneath. The MCP client is in-house on OTP (no third-party SDK), which is also why this port ships the full elicitation bridge (form and URL mode).

Toolkit

• Toolnexus.create_toolkit(opts) :: {:ok, toolkit} | {:error, term} — the aggregator. Toolnexus.create_toolkit!/1 returns the toolkit or raises.
• opts (keyword): :mcp_config, :skills_dir, :skills, :skill_provider, :skills_filter, :skill_sample_limit, :builtins, :agents, :extra_tools, :disable_tools, :disable_skills, :wait_for.
• Equivalents: createToolkit (js) · create_toolkit (py) · CreateToolkit (go) · Toolkit.create (java) · Toolkit.CreateAsync (c#).

Skills

• Toolnexus.Skill.load(input) :: %Toolnexus.Skill.Source{} — input is a path, a list of paths, or an options keyword.
• Toolnexus.Skill.list(input) :: %{skills: [...], skipped: [...]} — discover + validate; each skip is %{location, reason} with reasons missing-name · malformed-frontmatter · duplicate-name · unreadable.
• A data skill is a plain map: %{name, description, content, resources, base} (only :name and :content required).
• Equivalents: loadSkills / listSkills (js) · load_skills / list_skills (py) · LoadSkills / ListSkills (go) · SkillSource.load / listSkills (java) · SkillSource.Load / ListSkills (c#).

MCP · Adapters · Client

• Toolnexus.Mcp.load(config, opts \\ []) :: {:ok, mcp} | {:error, term} — mcp.tools.
• Toolnexus.Adapters.to_openai(tools) · to_anthropic(tools) · to_gemini(tools).
• Toolnexus.Client.create(opts) :: %Toolnexus.Client{} → Toolnexus.Client.run(client, prompt, toolkit, opts \\ []), Toolnexus.Client.stream(client, prompt, toolkit, opts \\ []).

Tools you build — native, HTTP, built-ins

• Toolnexus.Native.define_tool(name:, description:, input_schema?, execute:) — execute is fn args -> end or fn args, ctx -> end.
• Toolnexus.Http.tool(name:, description:, method:, url:, headers?, query?, body?, result_mode?, timeout?) — note the function is tool/1 (not http_tool); :timeout in ms.
• :builtins toggle → ten built-ins: bash · read · write · edit · grep · glob · webfetch · question · apply_patch · todowrite. (Toolnexus.Builtin.tools/0 · load/1.)
• Equivalents: defineTool / httpTool (js) · define_tool / http_tool (py) · NativeTool / HTTPTool (go) · NativeTool.of / HttpTool.of (java) · NativeTool.Of / HttpTool.Of (c#).

Sub-agents & teams

• Toolnexus.Agents.agent(name, does:, uses?, soul?/soul_file?, team?, budget?, model?, wait_for?).
• Toolnexus.Agents.run(agent, rt_opts, prompt) — result map %{status:, text:, total_tokens:, turns:, is_error:, pending:}.
• Toolnexus.Agents.as_tool(agent, rt_opts) · Toolnexus.Agents.compose_soul(dir) :: {soul, found}.
• Equivalents: agents.agent / .run / .asTool / composeSoul (js) · agent (py) · agents.New (go) · Agents.agent (java) · new Agent (c#).

A2A — serve & remote agents

• Toolnexus.Toolkit.serve(tk, addr, client:, a2a:, mcp?, on_task?, on_call?) :: Toolnexus.Serve.Handle.t() — handle.url · Toolnexus.Serve.stop/1.
• Toolnexus.A2A.agent(card:, headers?, timeout?, poll_every?) + create_toolkit(agents: [...]) / Toolnexus.Toolkit.add_agent(tk, card_url).
• Equivalents: tk.serve / tk.addAgent (js) · serve / add_agent (py) · Serve / AddAgent (go) · serve / addAgent (java) · ServeAsync / AddAgentAsync (c#).

Suspension & the human loop

• :wait_for (toolkit option; fn Request -> Answer).
• %Toolnexus.Request{id, kind, prompt, url, data, expires_at} (serializes expiresAt) · %Toolnexus.Answer{id, ok, data, reason}.
• Toolnexus.ToolResult.pending?/1 detects a suspension; a tool suspends by returning %ToolResult{is_error: true, metadata: %{pending: %Request{}}}.
• Equivalents: waitFor / pending (js) · wait_for / pending (py) · WaitFor / Pending (go) · waitFor / ToolResult.pending (java) · WithWaitFor / ToolResult.Pending (c#).

Media generation

Guide: Media generation · recipe: Generate images, video and speech · SPEC §7G.

• Toolnexus.Media.create(client | [client]) :: {:ok, t()} | {:error, Error.t()} · create!/1 — routes each verb to the first client whose supports? is true; falls through to the next only on status: :unavailable (dropping args that client does not accept). [] ⇒ media: no clients.
• Built-in clients, each (config \\ []): API a2e/1 (image, video, speech, talk; A2E_API_KEY) · elevenlabs/1 (speech, music, transcribe, cloneVoice; ELEVENLABS_API_KEY) · openai/1 (image, video, speech, transcribe; OPENAI_API_KEY) · openrouter/1 (image; OPENROUTER_API_KEY) · fal/1 (image, video; FAL_API_KEY); CLI grok/1 (image, video) · codex/1 (image) — prompt only. No key / CLI missing ⇒ :unavailable, no request.
• Config (Toolnexus.Media.Config, keyword list or map): model · models (%{verb => model}) · key (default: the env var, read at call time, never logged) · url · command (CLI argv prefix) · loop: [interval_ms, timeout_ms, on_progress] · gather: [mode: "url" | "download" | "inline", dir, max_bytes, keep] (built-ins default "download" into the temp dir) · http_client (fn %{method, url, headers, body, receive_timeout} -> {:ok, %{status, headers, body}} | {:error, e}) · http_options (extra Req options).
• Verbs, each (media, args, opts \\ []) with args a map or keyword list: image (prompt, width, height, aspectRatio, seed) · video (prompt, image, seconds, aspectRatio) · speech (text, voice) · music (prompt, seconds, instrumental, lyrics) · transcribe (audio, language) · clone_voice (name, samples) · talk (image, audio, text, voice). Inputs are http(s) URLs, file:// URLs or local paths. Snake-case atom keys work (:aspect_ratio); :provider_options overwrites the body last. An arg the routed-to first client does not accept ⇒ :failed.
• generate(media, verb, args, opts \\ []) — any verb ("cloneVoice", :clone_voice) · supports?(media, verb). opts: :signal (pid or zero-arity predicate) · :deadline (monotonic ms) · :progress (fn %{verb, client, job_id, status, elapsed_ms} -> any) · :provider_options.
• %Toolnexus.Media.Result{files: [%MediaFile{type, mime_type, url, path, data}], text, job_id, status} — text set for transcribe / clone_voice.
• @behaviour Toolnexus.Media.Client — name/1, supports?/2; optional args/2 and the verb callbacks image/3 … clone_voice/3, talk/3 taking (client, string_keyed_args, ctx). A client is a struct of that module or the module itself.
• Toolnexus.Media.tools(media) :: [Tool.t()] (source "media", one per supported verb, schema from the first supporting client), or create_toolkit(media: media).
• RunResult.files — %{type, mime_type, url | data, from, call_id}, in call order. Only image parts are sent back to the model; video and audio stay in files.
• Errors: {:error, %Toolnexus.Media.Error{message, status: :failed | :timeout | :cancelled | :unavailable, job_id}}; a signalled cancel raises Toolnexus.Media.Cancelled. A media tool never raises (is_error: true).
• Advanced: load_style(path) :: {:ok, map()} | {:error, Error.t()} + style_client(style, config \\ []) / style_client!/2 — a JSON style as a client.
• Equivalents: createMedia (js) · create_media (py) · CreateMedia (go) · Media.create (java) · Media.Create (c#) · toolnexus.media/create-media (clojure) · create_media (rust).