ClaudeAgentSDK.Tool.Registry (claude_agent_sdk v0.6.9)

View Source

GenServer that manages tool registration and execution for SDK MCP servers.

The Registry maintains a mapping of tool names to their metadata and execution modules, enabling:

  • Tool registration at server startup
  • Tool lookup by name
  • Tool execution dispatch
  • Concurrent access to tool definitions

Usage

{:ok, pid} = Registry.start_link([])

tool = %{
  name: :calculator,
  description: "Calculate",
  input_schema: %{type: "object"},
  module: MyTools.Calculator
}

:ok = Registry.register_tool(pid, tool)
{:ok, result} = Registry.execute_tool(pid, :calculator, %{"expression" => "2+2"})

Summary

Types

state()
tool_metadata()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

execute_tool(registry, name, input)

Executes a tool with given input.

get_tool(registry, name)

Gets a tool by name from the registry.

list_tools(registry)

Lists all registered tools.

register_tool(registry, tool)

Registers a tool with the registry.

start_link(opts \\ [])

Starts the registry GenServer.

Types

state()

@type state() :: %{tools: %{required(atom()) => tool_metadata()}}

tool_metadata()

@type tool_metadata() :: %{
  name: atom(),
  description: String.t(),
  input_schema: map(),
  module: module()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

execute_tool(registry, name, input)

@spec execute_tool(GenServer.server(), atom(), map()) ::
  {:ok, map()} | {:error, term()}

Executes a tool with given input.

Parameters

  • registry - Registry PID or name
  • name - Tool name (atom)
  • input - Input map matching tool's input_schema

Returns

  • {:ok, result} - Tool executed successfully
  • {:error, reason} - Execution failed

Examples

{:ok, result} = Registry.execute_tool(pid, :add, %{"a" => 5, "b" => 3})

get_tool(registry, name)

@spec get_tool(GenServer.server(), atom()) ::
  {:ok, tool_metadata()} | {:error, :not_found}

Gets a tool by name from the registry.

Parameters

  • registry - Registry PID or name
  • name - Tool name (atom)

Returns

  • {:ok, tool} - Tool found
  • {:error, :not_found} - Tool not found

Examples

{:ok, tool} = Registry.get_tool(pid, :calculator)

list_tools(registry)

@spec list_tools(GenServer.server()) :: {:ok, [tool_metadata()]}

Lists all registered tools.

Parameters

  • registry - Registry PID or name

Returns

{:ok, tools} where tools is a list of tool metadata maps.

Examples

{:ok, tools} = Registry.list_tools(pid)
Enum.each(tools, fn tool -> IO.puts(tool.name) end)

register_tool(registry, tool)

@spec register_tool(GenServer.server(), tool_metadata()) ::
  :ok | {:error, :already_registered}

Registers a tool with the registry.

Parameters

  • registry - Registry PID or name
  • tool - Tool metadata map

Returns

  • :ok - Successfully registered
  • {:error, :already_registered} - Tool already exists

Examples

tool = %{
  name: :add,
  description: "Add numbers",
  input_schema: %{type: "object"},
  module: MyTools.Add
}

:ok = Registry.register_tool(pid, tool)

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the registry GenServer.

Options

  • :name - Optional name for the registry

Examples

{:ok, pid} = Registry.start_link([])
{:ok, pid} = Registry.start_link(name: :my_registry)