Defines a discrete, composable unit of functionality within the Jido system.

Each Action represents a delayed computation that can be composed with others to build complex workflows. Actions are defined at compile-time and provide a consistent interface for validating inputs, executing workflows, and handling results.

Features

• Compile-time configuration validation
• Runtime input parameter validation
• Consistent error handling and formatting
• Extensible lifecycle hooks
• JSON serialization support

Usage

To define a new Action, use the Jido.Action behavior in your module:

defmodule MyAction do
  use Jido.Action,
    name: "my_action",
    description: "Performs my action",
    category: "processing",
    tags: ["example", "demo"],
    vsn: "1.0.0",
    schema: [
      input: [type: :string, required: true]
    ]

  @impl true
  def run(params, _context) do
    # Your action logic here
    {:ok, %{result: String.upcase(params.input)}}
  end
end

Callbacks

Implementing modules must define the following callback:

• run/2: Executes the main logic of the Action.

Optional callbacks for custom behavior:

• on_before_validate_params/1: Called before parameter validation.
• on_after_validate_params/1: Called after parameter validation.
• on_after_run/1: Called after the Action's main logic has executed.

Error Handling

Actions use the OK monad for consistent error handling. Errors are wrapped in Jido.Error structs for uniform error reporting across the system.

AI Tool Example

Actions can be converted to LLM compatible tools for use with LLM-based systems. This is particularly useful when building AI agents that need to interact with your system's capabilities:

# Define a weather action
iex> defmodule WeatherAction do
...>   use Jido.Action,
...>     name: "get_weather",
...>     description: "Gets the current weather for a location",
...>     category: "weather",
...>     tags: ["weather", "location"],
...>     vsn: "1.0.0",
...>     schema: [
...>       location: [
...>         type: :string,
...>         required: true,
...>         doc: "The city or location to get weather for"
...>       ]
...>     ]
...>
...>   @impl true
...>   def run(params, _context) do
...>     # Weather API logic here
...>     {:ok, %{temperature: 72, conditions: "sunny"}}
...>   end
...> end
{:module, WeatherAction, ...}

# Convert to tool format
iex> WeatherAction.to_tool()
%{
  "name" => "get_weather",
  "description" => "Gets the current weather for a location",
  "parameters" => %{
    "type" => "object",
    "properties" => %{
      "location" => %{
        "type" => "string",
        "description" => "The city or location to get weather for"
      }
    },
    "required" => ["location"]
  }
}

This tool definition can then be used with AI systems like OpenAI's function calling or other LLM frameworks that support tool/function specifications. The schema and validation ensure the AI system receives proper parameter constraints.

Testing

Actions can be tested directly by calling their run/2 function with test parameters and context:

defmodule WeatherActionTest do
  use ExUnit.Case

  test "gets weather for location" do
    params = %{location: "Portland"}
    context = %{}

    assert {:ok, result} = WeatherAction.run(params, context)
    assert is_map(result)
    assert result.temperature > 0
  end

  test "handles invalid location" do
    params = %{location: ""}
    context = %{}

    assert {:error, error} = WeatherAction.run(params, context)
    assert error.type == :validation_error
  end
end

For testing Actions in a more complete runtime environment, including signal routing, state management, and error handling, use Jido.Exec. This provides a full test harness for validating Action behavior within s:

test "weather action in " do
  {:ok, result} = Exec.run(WeatherAction, %{location: "Seattle"})
  assert result.weather_data.temperature > 0
end

See Jido.Exec documentation for more details on action-based testing.

Parameter Validation

Note on Validation: The validation process for Actions is intentionally open. Only fields specified in the schema are validated. Unspecified fields are not validated, allowing for easier Action composition. This approach enables Actions to accept and pass along additional parameters that may be required by other Actions in a chain without causing validation errors.