# `Jido`
[🔗](https://github.com/agentjido/jido/blob/v2.3.0/lib/jido.ex#L1)

自動 (Jido) - An autonomous agent framework for Elixir, built for workflows and
multi-agent systems.

## Quick Start

Create a Jido supervisor in your application:

    defmodule MyApp.Jido do
      use Jido, otp_app: :my_app
    end

Add to your supervision tree:

    children = [MyApp.Jido]

Start and manage agents:

    {:ok, pid} = MyApp.Jido.start_agent(MyAgent, id: "agent-1")
    pid = MyApp.Jido.whereis("agent-1")
    agents = MyApp.Jido.list_agents()
    :ok = MyApp.Jido.stop_agent("agent-1")

## Core Concepts

Jido agents are immutable data structures. The core operation is `cmd/2`:

    {agent, directives} = MyAgent.cmd(agent, MyAction)

- **Agents** — Immutable structs updated via commands
- **Actions** — Functions that transform agent state and may perform work
- **Directives** — Runtime-owned external effects (signals, processes, etc.)

Jido keeps agent decision logic pure. Actions may be pure or effectful.
Directives are for effects you want the runtime to own. If a step needs a
result back now to continue reasoning or update state, an effectful action is
acceptable; if delivery should belong to the runtime or an integration layer,
return a directive.

## For Tests

Use `JidoTest.Case` for isolation:

    defmodule MyAgentTest do
      use JidoTest.Case, async: true

      test "agent works", %{jido: jido} do
        {:ok, pid} = Jido.start_agent(jido, MyAgent)
        # ...
      end
    end

See `Jido.Agent` for defining agents and `Jido.Await` for coordination.

# `agent_id`

```elixir
@type agent_id() :: String.t() | atom()
```

# `partition`

```elixir
@type partition() :: term()
```

# `__using__`
*macro* 

Creates a Jido supervisor module.

## Options

  - `:otp_app` - Required. Your application name (e.g., `:my_app`).

## Example

    defmodule MyApp.Jido do
      use Jido, otp_app: :my_app
    end

Then add to your supervision tree in `lib/my_app/application.ex`:

    children = [MyApp.Jido]

Optionally configure in `config/config.exs` to customize defaults:

    config :my_app, MyApp.Jido,
      max_tasks: 2000,
      agent_pools: []

# `agent_count`

```elixir
@spec agent_count(atom()) :: non_neg_integer()
```

Returns the count of running agents in a Jido instance.

## Examples

    count = Jido.agent_count(MyApp.Jido)
    # => 5

# `agent_count`

```elixir
@spec agent_count(
  atom(),
  keyword()
) :: non_neg_integer()
```

# `agent_pool_name`

```elixir
@spec agent_pool_name(atom(), atom()) :: atom()
```

Returns the AgentPool name for a specific pool in a Jido instance.

# `agent_supervisor_name`

```elixir
@spec agent_supervisor_name(atom()) :: atom()
```

Returns the AgentSupervisor name for a Jido instance.

# `alive?`

Check if an agent process is alive and responding.

See `Jido.Await.alive?/1` for details.

# `await`

Wait for an agent to reach a terminal status.

See `Jido.Await.completion/3` for details.

# `await_all`

Wait for all agents to reach terminal status.

See `Jido.Await.all/3` for details.

# `await_any`

Wait for any agent to reach terminal status.

See `Jido.Await.any/3` for details.

# `await_child`

Wait for a child agent to reach a terminal status.

See `Jido.Await.child/4` for details.

# `cancel`

Request graceful cancellation of an agent.

See `Jido.Await.cancel/2` for details.

# `debug`

```elixir
@spec debug() :: Jido.Debug.level()
```

Controls debug mode for the default Jido instance (`Jido.Default`).

- `debug()` — returns current debug level
- `debug(:on)` — enable developer-friendly verbosity
- `debug(:verbose)` — enable maximum detail
- `debug(:off)` — disable debug overrides

# `debug`

```elixir
@spec debug(Jido.Debug.level()) :: :ok
```

# `debug`

```elixir
@spec debug(
  Jido.Debug.level(),
  keyword()
) :: :ok
```

# `default_instance`

```elixir
@spec default_instance() :: atom()
```

Returns the default Jido instance name.

Used by `Jido.start/1` for scripts and Livebook quick-start.

# `generate_id`

Generate a unique identifier.

Delegates to `Jido.Util.generate_id/0`.

# `get_action_by_slug`

Gets an Action by its slug.

# `get_child`

Get a specific child's PID by tag.

See `Jido.Await.get_child/2` for details.

# `get_children`

Get the PIDs of all children of a parent agent.

See `Jido.Await.get_children/1` for details.

# `get_plugin_by_slug`

Gets a Plugin by its slug.

# `get_sensor_by_slug`

Gets a Sensor by its slug.

# `hibernate`

```elixir
@spec hibernate(atom(), Jido.Agent.t()) :: :ok | {:error, term()}
```

Hibernate an agent using the given Jido instance.

# `hibernate`

```elixir
@spec hibernate(atom(), Jido.Agent.t(), keyword()) :: :ok | {:error, term()}
```

# `list_actions`

Lists discovered Actions with optional filtering.

# `list_agents`

```elixir
@spec list_agents(atom()) :: [{String.t(), pid()}]
```

Lists all agents running in a Jido instance.

Returns a list of `{id, pid}` tuples.

## Examples

    agents = Jido.list_agents(MyApp.Jido)
    # => [{"agent-1", #PID<0.123.0>}, {"agent-2", #PID<0.124.0>}]

# `list_agents`

```elixir
@spec list_agents(
  atom(),
  keyword()
) :: [{String.t(), pid()}]
```

# `list_demos`

Lists discovered Demos with optional filtering.

# `list_plugins`

Lists discovered Plugins with optional filtering.

# `list_sensors`

Lists discovered Sensors with optional filtering.

# `parent_binding`

```elixir
@spec parent_binding(atom(), String.t()) :: {:ok, map()} | :error
```

Fetches the persisted logical parent binding for a child agent.

This is the stable runtime relationship lookup API for orchestration layers
that need to inspect the live parent/child graph without depending on raw
`RuntimeStore` hive layout.

Returns `{:ok, binding}` when present, or `:error` when no binding exists.

## Examples

    {:ok, binding} = Jido.parent_binding(MyApp.Jido, "child-123")
    assert binding.parent_id == "parent-456"

# `parent_binding`

```elixir
@spec parent_binding(atom(), String.t(), keyword()) :: {:ok, map()} | :error
```

# `refresh_discovery`

Refreshes the Discovery catalog.

# `registry_name`

```elixir
@spec registry_name(atom()) :: atom()
```

Returns the Registry name for a Jido instance.

# `runtime_store_name`

```elixir
@spec runtime_store_name(atom()) :: atom()
```

Returns the RuntimeStore name for a Jido instance.

# `scheduler_name`

```elixir
@spec scheduler_name(atom()) :: atom()
```

Returns the Scheduler name for a Jido instance.

# `start`

```elixir
@spec start(keyword()) :: {:ok, pid()} | {:error, term()}
```

Start the default Jido instance for scripts and Livebook.

This is an idempotent convenience function - safe to call multiple times
(returns `{:ok, pid}` even if already started).

## Examples

    # In a script or Livebook
    {:ok, _} = Jido.start()
    {:ok, pid} = Jido.start_agent(Jido.default_instance(), MyAgent)

    # With custom options
    {:ok, _} = Jido.start(max_tasks: 2000)

## Options

Same as `start_link/1`, but `:name` defaults to `Jido.Default`.

# `start_agent`

```elixir
@spec start_agent(atom(), module() | struct(), keyword()) ::
  DynamicSupervisor.on_start_child()
```

Starts an agent under a specific Jido instance.

## Examples

    {:ok, pid} = Jido.start_agent(MyApp.Jido, MyAgent)
    {:ok, pid} = Jido.start_agent(MyApp.Jido, MyAgent, id: "custom-id")

# `start_link`

Starts a Jido instance supervisor.

## Options
  - `:name` - Required. The name of this Jido instance (e.g., `MyApp.Jido`)

## Example

    {:ok, pid} = Jido.start_link(name: MyApp.Jido)

# `stop`

```elixir
@spec stop(atom()) :: :ok
```

Stop a Jido instance.

Defaults to stopping the default instance (`Jido.Default`).

## Examples

    Jido.stop()
    Jido.stop(MyApp.Jido)

# `stop_agent`

```elixir
@spec stop_agent(atom(), pid() | String.t()) :: :ok | {:error, :not_found}
```

Stops an agent by pid or id.

## Examples

    :ok = Jido.stop_agent(MyApp.Jido, pid)
    :ok = Jido.stop_agent(MyApp.Jido, "agent-id")

# `stop_agent`

```elixir
@spec stop_agent(atom(), pid() | String.t(), keyword()) :: :ok | {:error, :not_found}
```

# `task_supervisor_name`

```elixir
@spec task_supervisor_name(atom()) :: atom()
```

Returns the TaskSupervisor name for a Jido instance.

# `thaw`

```elixir
@spec thaw(atom(), module(), term()) :: {:ok, Jido.Agent.t()} | {:error, term()}
```

Thaw an agent using the given Jido instance.

# `thaw`

```elixir
@spec thaw(atom(), module(), term(), keyword()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}
```

# `whereis`

```elixir
@spec whereis(atom(), String.t()) :: pid() | nil
```

Looks up an agent by ID in a Jido instance's registry.

Returns the pid if found, nil otherwise.

## Examples

    pid = Jido.whereis(MyApp.Jido, "agent-123")

# `whereis`

```elixir
@spec whereis(atom(), String.t(), keyword()) :: pid() | nil
```