Toolnexus.Toolkit (toolnexus v0.9.4)

Copy Markdown View Source

Toolkit — aggregates dynamic MCP tools + the skill tool + built-ins + remote A2A agents + custom tools into a single uniform list, with provider adapters and a single execute/4 router (SPEC §4).

Assembly is deterministic: (1) drop any builtin whose name a host extra_tools entry provides (a host can shadow a builtin); (2) concatenate the remaining sources in the order MCP → skill → builtin → agents → extra_tools; (3) dedupe by name, first wins. disable_tools drops tools by their final exposed name across every source.

The struct exposes :tools and :prompt directly, so it plugs straight into Toolnexus.Client.run/4.

Summary

Types

t()

Functions

add_agent(tk, agent_or_card_url, opts \\ [])

Fetch a remote A2A agent's card at runtime and register its skills as tools. Accepts an Agent descriptor (map/keyword) or a bare card URL (with optional opts for headers/timeout/poll_every). First-name-wins dedupe.

build(opts)

Build a Toolkit. Options (keyword list or map)

close(toolkit)

Disconnect every MCP client.

execute(tk, name, args, ctx \\ nil)

Route to the right tool and run it. Unknown name ⇒ an error ToolResult.

get(toolkit, name)

A tool by name, or nil.

mcp_status(toolkit)

Each MCP server's connection status.

register(tk, tools)

Add tools at runtime (native, http, or any custom Tool). First name wins; duplicates are skipped with a warning. Returns the updated toolkit.

serve(tk, addr, opts \\ [])

Serve this toolkit as an agent over HTTP (SPEC §7B/§7C). When the A2A profile is present (opts[:a2a], or a top-level a2a config block the toolkit was built from) it mounts the Agent Card + JSON-RPC endpoint fulfilled by opts[:client]; a message's A2A contextId keys the conversation via Client.ask. When the MCP profile is present (opts[:mcp], or a top-level mcpServer config block) it mounts a streamable-HTTP MCP server at /mcp exposing the toolkit's unified tools. Returns a stoppable Toolnexus.Serve.Handle.

skills_prompt(toolkit)

Markdown skill catalog for the system prompt.

to_anthropic(toolkit)

Anthropic tool schema for all tools.

to_gemini(toolkit)

Gemini tool schema for all tools.

to_openai(toolkit)

OpenAI tool schema for all tools.

tools(toolkit)

All tools (mcp tools + skill tool + builtins + agents + extras), in insertion order.

Types

t()

@type t() :: %Toolnexus.Toolkit{
  a2a_config: map() | nil,
  by_name: %{required(String.t()) => Toolnexus.Tool.t()},
  mcp: Toolnexus.Mcp.Source.t() | nil,
  mcp_server_config: map() | nil,
  prompt: String.t(),
  skill: Toolnexus.Skill.Source.t() | nil,
  tools: [Toolnexus.Tool.t()]
}

Functions

add_agent(tk, agent_or_card_url, opts \\ [])

@spec add_agent(t(), map() | keyword() | String.t(), keyword() | map()) :: t()

Fetch a remote A2A agent's card at runtime and register its skills as tools. Accepts an Agent descriptor (map/keyword) or a bare card URL (with optional opts for headers/timeout/poll_every). First-name-wins dedupe.

build(opts)

@spec build(keyword() | map()) :: t()

Build a Toolkit. Options (keyword list or map):

  • :mcp_config — path to an MCP config file, raw JSON, or a parsed map
  • :skills_dir — one or more skill roots
  • :skills — skills supplied as data, bypassing the filesystem (§3, S1)
  • :skill_provider — 0-arity fun lazily supplying data skills (§3, S1)
  • :skills_filter — per-agent skill allowlist keyed on name (§3, S2)
  • :skill_sample_limit — sibling-file cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5)
  • :disable_tools — drop tools by their FINAL exposed name across every source; composes with the per-server/per-skill filters
  • :disable_skills — drop skills by name from the skill catalog (sugar over a drop-list in :skills_filter)
  • :extra_tools — your own custom tools, always added to the toolkit
  • :builtins — built-in tools toggle (§4A). Default ON. When absent, a top-level builtins key on a parsed config map is consulted
  • :agents — remote A2A agents (§7A); a top-level agents config block is merged in as well
  • :wait_for — §10 host resolver; bridges MCP elicitation
  • :deadline (ms) — bounds the MCP load (§2 Gap 3)

close(toolkit)

@spec close(t()) :: :ok

Disconnect every MCP client.

execute(tk, name, args, ctx \\ nil)

@spec execute(t(), String.t(), map(), Toolnexus.Context.t() | nil) ::
  Toolnexus.ToolResult.t()

Route to the right tool and run it. Unknown name ⇒ an error ToolResult.

get(toolkit, name)

@spec get(t(), String.t()) :: Toolnexus.Tool.t() | nil

A tool by name, or nil.

mcp_status(toolkit)

@spec mcp_status(t()) :: %{required(String.t()) => String.t()}

Each MCP server's connection status.

register(tk, tools)

@spec register(t(), [Toolnexus.Tool.t()] | Toolnexus.Tool.t()) :: t()

Add tools at runtime (native, http, or any custom Tool). First name wins; duplicates are skipped with a warning. Returns the updated toolkit.

serve(tk, addr, opts \\ [])

@spec serve(t(), String.t(), keyword()) :: Toolnexus.Serve.Handle.t()

Serve this toolkit as an agent over HTTP (SPEC §7B/§7C). When the A2A profile is present (opts[:a2a], or a top-level a2a config block the toolkit was built from) it mounts the Agent Card + JSON-RPC endpoint fulfilled by opts[:client]; a message's A2A contextId keys the conversation via Client.ask. When the MCP profile is present (opts[:mcp], or a top-level mcpServer config block) it mounts a streamable-HTTP MCP server at /mcp exposing the toolkit's unified tools. Returns a stoppable Toolnexus.Serve.Handle.

skills_prompt(toolkit)

@spec skills_prompt(t()) :: String.t()

Markdown skill catalog for the system prompt.

to_anthropic(toolkit)

@spec to_anthropic(t()) :: [map()]

Anthropic tool schema for all tools.

to_gemini(toolkit)

@spec to_gemini(t()) :: [map()]

Gemini tool schema for all tools.

to_openai(toolkit)

@spec to_openai(t()) :: [map()]

OpenAI tool schema for all tools.

tools(toolkit)

@spec tools(t()) :: [Toolnexus.Tool.t()]

All tools (mcp tools + skill tool + builtins + agents + extras), in insertion order.