Walkthrough: Agent Tool Wiring with AshJido

Copy Markdown View Source

This walkthrough shows a practical, safe pattern for exporting and executing generated actions as tools.

1. Discover Generated Actions

Use AshJido.Tools.actions/1 for either a single resource or an entire domain.

# Resource-level
resource_actions = AshJido.Tools.actions(MyApp.Accounts.User)

# Domain-level
all_actions = AshJido.Tools.actions(MyApp.Accounts)

Use domain-level discovery when you want one unified tool catalog for an agent.

2. Export Tool Payloads

AshJido.Tools.tools/1 returns tool maps with:

  • name
  • description
  • parameters_schema
  • function
tools = AshJido.Tools.tools(MyApp.Accounts)

create_user_tool = Enum.find(tools, &(&1.name == "create_user"))

3. Safe Execution Wrapper Pattern

Wrap tool execution to normalize context handling and JSON decode behavior.

def run_tool(tool, params, domain, base_context \\ %{}) do
  context = Map.put(base_context, :domain, domain)

  case tool.function.(params, context) do
    {:ok, json} ->
      {:ok, Jason.decode!(json)}

    {:error, json} ->
      {:error, Jason.decode!(json)}
  end
end

Guidelines:

  1. Keep tool params as string-key maps for LLM integration paths.
  2. Always inject domain into execution context.
  3. Treat {:ok, json} and {:error, json} as structured payloads.

4. Metadata Strategy (tags, category, vsn)

Set metadata in DSL so tools are easier to route and version.

jido do
  action :create,
    name: "create_user",
    category: "ash.accounts.write",
    tags: ["accounts", "write", "user"],
    vsn: "1.2.0"
end

Metadata can be read from generated modules:

MyApp.Accounts.User.Jido.Create.category()
MyApp.Accounts.User.Jido.Create.tags()
MyApp.Accounts.User.Jido.Create.vsn()

This gives a stable contract for tool catalogs, capability routing, and compatibility tracking.