Actions Catalog

Copy Markdown View Source

This guide is the quick inventory of built-in Jido.AI.Actions.* modules and what each one is for.

Production Baseline (Standalone Surface)

For direct app integration (Jido.Exec-driven), this is the primary standalone action surface:

  1. Core generation:
  2. Tool orchestration:
  3. Planning templates:
  4. Retrieval memory operations:
  5. Quota operations:
  6. Skill orchestration:
  7. Reasoning templates (optional):
  8. Dedicated strategy orchestration:
  9. Compatibility convenience:

LLM Actions

Tool Calling Actions

Planning Actions

Retrieval Actions

Quota Actions

  • Jido.AI.Actions.Quota.GetStatus
    • Use when you need the current rolling quota snapshot for one scope.
    • Required params: none. Optional params: scope.
    • Scope resolution when scope is omitted: context[:plugin_state][:quota][:scope] -> context[:state][:quota][:scope] -> context[:agent][:id] -> "default".
    • Output contract: %{quota: %{scope, window_ms, usage, limits, remaining, over_budget?}}.
    • Runnable example: examples/scripts/demo/actions_quota_runtime_demo.exs
  • Jido.AI.Actions.Quota.Reset
    • Use when you need to clear rolling quota counters for one scope.
    • Required params: none. Optional params: scope.
    • Scope resolution when scope is omitted: context[:plugin_state][:quota][:scope] -> context[:state][:quota][:scope] -> context[:agent][:id] -> "default".
    • Output contract: %{quota: %{scope, reset}}.
    • Runnable example: examples/scripts/demo/actions_quota_runtime_demo.exs

Skill Actions

  • Jido.AI.Actions.Skill.LoadSkill
    • Use when a prompt advertises a compact skill index and the selected skill body should be loaded only on demand.
    • Required params: name. Optional params: include_metadata (default true).
    • Output contract: %{name, description, instructions, resources} plus metadata fields when requested.
    • Pair with Jido.AI.Skill.Prompt.render_registry_index/1 for tag-filtered skill indexes, or use agent_skills: for scoped filesystem and runtime-spec catalogs.
    • Runtime specs configured with resource_provider: are activated through the same native action and receive provider-normalized resource listings.
  • Jido.AI.Actions.Skill.LoadResource

    • Use after LoadSkill when skill instructions refer to one bundled or provider-backed text resource.

    • Required params: name plus exactly one selector: resource_id for provider-backed runtime skills, or relative_path for filesystem skills. path remains accepted only as a filesystem compatibility alias.

    • Provider-backed example:

      {
  "name": "about-jaicool",
  "resource_id": "b7754895-90f8-4594-b6be-c80fd0859545"
}

    • Output contract: %{skill, resource_id, content, size, mime_type} for provider resources or %{skill, path, content, size} for filesystem resources.

    • Requires the skill to be active in the same runtime session and enforces the configured resource policy. Provider-backed resources are fetched fresh on every call, authorized against the activated listing, and validated for identifier identity, size, and UTF-8 text before returning.

    • Resource listings keep resources as the complete aggregate. references, assets, and scripts are filtered views; entries intentionally appear in both the aggregate and typed lists.

Reasoning Actions

Shared Helpers

Not Standalone: Strategy Internals

Reasoning strategy command atoms and lifecycle/event handlers are intentionally not standalone actions:

  • :cod_start, :ai_react_start, :cot_start, :aot_start, :tot_start, :got_start, :trm_start, :adaptive_start
  • *_llm_result, *_llm_partial, request error lifecycle handlers, worker event handlers

These belong to strategy orchestration and are not app-level AI primitives.

Selection Heuristic

  • Need chat/completion/embed/object output: use LLM actions.
  • Need model-directed tool use: use Tool Calling actions.
  • Need structured planning templates: use Planning actions.
  • Need in-process memory upsert/recall/clear primitives: use Retrieval actions.
  • Need rolling quota status or a quota counter reset operation: use Quota actions.
  • Need lazy skill body loading from a compact prompt index: use LoadSkill.
  • Need one file from an activated skill: use LoadResource.
  • Need explicit reasoning strategy execution as a callable capability: use RunStrategy.

Failure Mode: Action Used Outside Expected Context

Symptom:

  • runtime errors due to missing tool context or model/provider config

Fix:

  • pass required context explicitly
  • verify model/provider config and tool maps before execution
  • for plugin-routed calls, ensure plugin state keys match mounted capability

Next