Jido.BehaviorTree.Agent (Jido Behavior Tree v1.0.0)

View Source

A simple behavior tree executor using a GenServer.

This agent provides a stateful execution environment for behavior trees, maintaining the tree state and blackboard between ticks. It supports both manual and automatic execution modes.

Features

  • Execute behavior trees with automatic state management
  • Maintain shared blackboard between executions
  • Support for manual or automatic tree progression
  • Built-in telemetry and logging

Example Usage

# Create a simple tree
tree = Jido.BehaviorTree.Tree.new(simple_node)

# Start the agent
{:ok, agent} = Jido.BehaviorTree.Agent.start_link(
  tree: tree,
  blackboard: %{status: :ready},
  mode: :manual
)

# Tick the tree manually
status = Jido.BehaviorTree.Agent.tick(agent)

# Get current blackboard
bb = Jido.BehaviorTree.Agent.blackboard(agent)

Summary

Types

mode()

Agent execution mode

state()

Agent state

Functions

blackboard(pid)

Gets the current blackboard.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

directives(pid)

Gets directives emitted on the most recent tick.

get(pid, key, default \\ nil)

Gets a value from the blackboard.

halt(pid)

Halts the agent and cleans up the tree.

jido_agent(pid)

Gets the current Jido agent context (if configured).

mode(pid)

Gets the current execution mode.

put(pid, key, value)

Puts a value in the blackboard.

replace_root(pid, new_root)

Replaces the root node of the tree.

set_mode(pid, new_mode)

Sets the execution mode.

start_link(opts)

Starts a behavior tree agent.

status(pid)

Gets the status from the most recent tick.

tick(pid)

Executes a single tick of the behavior tree.

Types

mode()

@type mode() :: :manual | :auto

Agent execution mode

state()

@type state() :: %{
  tree: Jido.BehaviorTree.Tree.t(),
  blackboard: Jido.BehaviorTree.Blackboard.t(),
  jido_agent: Jido.Agent.t() | nil,
  last_directives: [Jido.Agent.directive()],
  last_status: :idle | Jido.BehaviorTree.Status.t(),
  mode: mode(),
  interval: non_neg_integer() | nil,
  timer_ref: reference() | nil,
  tick_count: non_neg_integer()
}

Agent state

Functions

blackboard(pid)

@spec blackboard(pid()) :: Jido.BehaviorTree.Blackboard.t()

Gets the current blackboard.

Examples

bb = Jido.BehaviorTree.Agent.blackboard(agent)

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

directives(pid)

@spec directives(pid()) :: [Jido.Agent.directive()]

Gets directives emitted on the most recent tick.

get(pid, key, default \\ nil)

@spec get(pid(), term(), term()) :: term()

Gets a value from the blackboard.

Examples

value = Jido.BehaviorTree.Agent.get(agent, :key, "default")

halt(pid)

@spec halt(pid()) :: :ok

Halts the agent and cleans up the tree.

Examples

:ok = Jido.BehaviorTree.Agent.halt(agent)

jido_agent(pid)

@spec jido_agent(pid()) :: Jido.Agent.t() | nil

Gets the current Jido agent context (if configured).

mode(pid)

@spec mode(pid()) :: mode()

Gets the current execution mode.

Examples

mode = Jido.BehaviorTree.Agent.mode(agent)

put(pid, key, value)

@spec put(pid(), term(), term()) :: :ok

Puts a value in the blackboard.

Examples

:ok = Jido.BehaviorTree.Agent.put(agent, :key, "value")

replace_root(pid, new_root)

@spec replace_root(pid(), Jido.BehaviorTree.Node.t()) :: :ok

Replaces the root node of the tree.

Examples

:ok = Jido.BehaviorTree.Agent.replace_root(agent, new_root)

set_mode(pid, new_mode)

@spec set_mode(pid(), mode()) ::
  :ok | {:error, Jido.BehaviorTree.Error.BehaviorTreeError.t()}

Sets the execution mode.

When changing to :auto mode, automatic ticking will start. When changing to :manual mode, automatic ticking will stop. Returns a validation error when mode is not :manual or :auto.

Examples

:ok = Jido.BehaviorTree.Agent.set_mode(agent, :auto)

start_link(opts)

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

Starts a behavior tree agent.

Options

  • :tree - The behavior tree to execute (required)
  • :blackboard - Initial blackboard data (default: empty blackboard)
  • :jido_agent - Optional %Jido.Agent{} for Action-node state/directive integration
  • :mode - Execution mode, either :manual or :auto (default: :manual)
  • :interval - Tick interval in milliseconds for auto mode (default: 1000)

Examples

{:ok, agent} = Jido.BehaviorTree.Agent.start_link(
  tree: tree,
  blackboard: %{user_id: 123},
  mode: :auto,
  interval: 2000
)

status(pid)

@spec status(pid()) :: :idle | Jido.BehaviorTree.Status.t()

Gets the status from the most recent tick.

Returns :idle before the first tick.

tick(pid)

@spec tick(pid()) :: Jido.BehaviorTree.Status.t()

Executes a single tick of the behavior tree.

Returns the status of the tree execution.

Examples

status = Jido.BehaviorTree.Agent.tick(agent)