API Reference — Elixir

Package toolnexus (Hex), Elixir ≥ 1.16 / OTP 26. See the combined API Reference for every symbol shown in six-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 six 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#).