Jido: what "agent" means
Part of Agent Definition Research. Produced by running RESEARCH_PROMPT. Evidence from the agentjido/jido source (v2.3.2, Apache-2.0, maintained by Mike Hostetler) and the jido_ai companion. Elixir/OTP framework; README: "Jido helps you build agent systems as ordinary Elixir and OTP software. Agents hold state and implement cmd/2. Actions do work and transform that state. Signals route events into the system. Directives describe effects for the runtime to execute... AI is optional."
The agent noun (primary-source quotes)
- The agent is not the process. From
guides/core-loop.md: Agent = "Immutable struct + module: defines schema, handles cmd/2, pure decision logic"; AgentServer = "GenServer process: holds agent state, executes directives, routes signals." - Moduledoc (
lib/jido/agent.ex): "An Agent is an immutable data structure that holds state and can be updated via commands... The fundamental operation iscmd/2:{agent, directives} = MyAgent.cmd(agent, MyAction). Key invariants: the returned agent is always complete...; directives are runtime-owned external effects only, they never modify agent state... The Agent struct is immutable. All operations return new agent structs. Server/OTP integration is handled separately byJido.AgentServer." - Struct fields (Zoi schema):
id,agent_module,name,description,category,tags,vsn,schema(state-validation schema),state(map). - README framing: "Functional agent state model inspired by Elm/Redux:
cmd/2as the core operation: actions in, updated agent + directives out." - Conceptual model: a split. The definition is a compile-time module (
use Jido.Agent, agent-as-config); the value is an immutable struct (agent-as-state); the running instance is a supervised GenServer (AgentServer, agent-as-process). Jido is the only product in the study that makes the state/process distinction formally explicit and keeps the decision logic pure.
Subagents
- First-class and dynamic: the
%SpawnAgent{}directive (lib/jido/agent/directive.ex): "Spawn a child agent with parent-child hierarchy tracking... Child's parent reference points to the spawning agent; parent monitors the child process; parent tracks child in its children map by tag; child exit signals are delivered to parent asjido.agent.child.exit; child can useemit_to_parent/3while attached." - Logical hierarchy is not the same as OTP supervision: "The logical relationship is independent from OTP supervisory ancestry. If the child later becomes orphaned, the current parent ref is cleared and the child must be explicitly reattached with
AdoptChild." - Fields on spawn: agent module or pre-built struct,
tag,opts,meta,restartpolicy (default:transient). - Orphan policy is a config knob:
on_parent_deathon the child server::stop(default),:continue,:emit_orphan. - No depth or fan-out limits found in code.
- Communication is signals (CloudEvents-compliant envelopes):
emit_to_parent/3upward; lifecycle signals (child.started,child.exit) downward to the parent's children map. No shared state; isolation is BEAM process isolation. - Related machinery:
Jido.Pod("agent with a canonical named topology of collaborators" persisted in state and reconciled after thaw) and Poolboy-based pre-warmed agent worker pools.
Configuration surface (what, where, why)
- Compile-time config (
use Jido.Agent, ...):name,description,category,tags,vsn,schema(NimbleOptions or Zoi state schema),strategy("Execution strategy module or {module, opts}. Default: Jido.Agent.Strategy.Direct"),plugins,signal_routes("Compile-time signal route table. Each route maps signal type/pattern to an action target"),default_plugins(override/disable),schedules("Declarative cron schedules as {cron_expr, signal_type}"),jido(instance module). - Server start options (
Jido.AgentServer.start_link):agent(required),id(auto-generated if absent),initial_state,registry,default_dispatch,error_policy,max_queue_size(default 10,000),parent,on_parent_death,spawn_fun,debug. - Where config lives: macro options in code (compile-time), keyword opts at server start, application config for Jido instances (
use Jido, otp_app: :my_app, multiple isolated instances per app, "no global singletons"). - Stated rationale is the purity boundary (README): "Jido keeps agent decisions and state transitions explicit, actions may be pure or effectful, and directives are for effects you want the runtime to own." Directives vs StateOps encode this: StateOps (SetState, ReplaceState, ...) are handled by the strategy and "never reach the runtime"; directives are the inverse.
- jido_ai layers LLM behavior on top:
use Jido.AI.Agentwires a ReAct strategy,model:resolved at runtime, tools are ordinary Jido actions, and each instance gets its own Task.Supervisor via a default skill plugin.
Binding time
- Compile time: routes, plugins, merged state schema, plugin actions and schedules are validated and baked into module attributes; plugin requirement violations fail the build. "Cannot add new routes or plugins at runtime."
- Struct creation (
new/1): initial state assembled from schema defaults + plugin defaults + opts;strategy.init/2runs. - Runtime-mutable via directives: cron jobs (
%Cron{}/%CronCancel{}), sensors (%StartSensor{}/%StopSensor{}), children (%SpawnAgent{}/%StopChild{}/%AdoptChild{}), and the state map itself throughcmd/2(functionally, new struct each time). - Versioning:
vsnis a user-supplied string, not auto-incremented. TheJido.Agent.Identitydefault plugin separately keeps a monotonicrevinteger for identity-profile mutations ("Identity state is immutable: updates produce a new struct with a bumped revision") plus created/updated timestamps. - Definition changes are code deploys (BEAM releases/hot upgrades); nothing product-specific governs in-flight instances.
Relationships between nouns
- Agent (struct+module) 1:1-per-instance AgentServer (process); many instances of one agent module may run, each with its own id.
- Strategy 1:1 agent module (compile-time): owns how
cmd/2executes (Direct default; ReAct in jido_ai driven bytick/2+%Schedule{}directives). - Plugin N:1 agent module (compile-time): contributes actions, routes, schedules, state defaults.
- Sensor N:1 server (runtime): transforms external events into signals.
- Signal, a CloudEvents envelope, the universal message. Instruction, normalized action + params + context (jido_action package). Directive, runtime-owned effect emitted by
cmd/2. StateOp, internal state change, never reaches the runtime. - Parent:child, logical refs (
ParentRefwith pid/id/tag/meta;childrenmap of tag → ChildInfo) layered over a flat DynamicSupervisor (Jido.AgentSupervisor); death coupling is per-child policy, not supervision-tree structure. - No session noun. The closest is the server instance's lifetime plus hibernate/thaw persistence.
Lifecycle
- Create:
MyAgent.new(id:, state:), pure. Start:Jido.AgentServer.start_link(agent: MyAgent)under a DynamicSupervisor;post_initbuilds the signal router, starts plugin children and sensors, restores from storage if the lifecycle module says so, registers schedules, notifies the parent, and lands in:idle. - Status machine:
:initializing → :idle → :processing → :idle(or:stopping). - The loop is event-driven, not autonomous polling: signals arrive via
call/2(sync) orcast/2(async); processing runs in a Task; a drain loop executes queued directives; multi-step reasoning (ReAct) is driven by the strategy'stick/2scheduled via directives. The customer's BEAM application owns the loop; Jido is a library/framework, not a hosted service. - Stop:
%Directive.Stop{}from insidecmd/2, or supervisor shutdown.terminate/2hibernates via the lifecycle module, cancels crons, stops sensors. - Persistence:
Jido.Persisthibernate/thaw (checkpoint/2/restore/2callbacks to pluggable storage);Jido.Agent.InstanceManagergives keyed singletons with idle-timeout auto-hibernate. Pods persist and reconcile their collaborator topology after thaw.
What makes it "an agent" here (our inference)
Our inference: Jido defines an agent as a pure state machine with an identity, an immutable struct whose only operation is cmd(agent, action) → {new_agent, directives}, and treats everything the industry usually bundles into "agent" (process, loop, effects, scheduling, children) as runtime concerns owned by a separate GenServer. LLM reasoning is literally optional ("AI is optional"). It is the study's cleanest separation of agent-as-definition / agent-as-state / agent-as-process, and its parent-child model (logical refs with explicit orphan policy, decoupled from supervision) is the most nuanced subagent lifetime-coupling design observed.
Open questions
- No session/run noun: how multi-turn conversations map onto instances is left to the application (jido_ai adds request tracking in state).
vsnis free-form and unenforced; no migration story for state schema changes across hibernate/thaw was found.- No nesting/fan-out limits: supervision defaults are the only backpressure besides
max_queue_size. - The 49-repo org split (jido, jido_action, jido_signal, jido_ai) spreads the definition across packages; API stability across them is unverified.
