Choosing A Runtime Pattern

Jido now has a few different runtime building blocks, and they are close enough that it is easy to reach for the wrong one.

This guide is the short decision tree.

The Simple Mental Model

• use MyApp.Jido.start_agent/2 (or Jido.start_agent/3) or Jido.AgentServer.start_link/1 for one live agent
• use Directive.SpawnAgent for a live tracked child of the current parent
• use Jido.Agent.InstanceManager for one named durable agent
• use Jido.Pod for one named durable team of agents
• use partition to namespace any of the above in a shared Jido instance

The important boundary is this:

• lifecycle is chosen by AgentServer, SpawnAgent, InstanceManager, or Pod
• tenancy is chosen by partition

partition is not a lifecycle mechanism by itself. It is a namespace boundary.

Pick The Right Tool

When To Use SpawnAgent

Use SpawnAgent when the child is part of the current live workflow:

• worker fan-out
• short-lived coordinators
• ephemeral sub-agents
• parent-owned runtime behavior

Good fit:

Directive.spawn_agent(MyWorker, :researcher,
  opts: %{id: "research-1", on_parent_death: :stop}
)

Do not use SpawnAgent when what you really want is:

• storage-backed hibernate/thaw
• durable keyed reacquisition
• a named runtime that should survive independently of one parent turn

That is InstanceManager territory instead.

When To Use InstanceManager

Use Jido.Agent.InstanceManager when the durable unit is one named agent:

{:ok, pid} = Jido.Agent.InstanceManager.get(:sessions, "user-123")

That gives you:

• keyed lookup
• optional storage-backed thaw
• ordinary single-agent runtime semantics

If the durable unit is a team or workspace with multiple named members, that is no longer “one durable agent.” That is where Jido.Pod starts to make sense.

When To Use Pod

Use Jido.Pod when the durable unit is a structured team:

• a workspace
• a named pipeline
• an editorial or planning team
• a durable agent tree with eager and lazy members

{:ok, pod_pid} = Jido.Pod.get(:workspace_pods, "workspace-123")
{:ok, reviewer_pid} = Jido.Pod.ensure_node(pod_pid, :reviewer)

Pods are the right abstraction when you care about:

• durable topology
• manager-led reconcile after thaw
• hierarchical runtime ownership
• nested pod nodes

Pods are not just “a nicer SpawnAgent.” They are the durable topology layer. If you want the shortest end-to-end example, start with Pods: Canonical Example.

Where partition Fits

partition is orthogonal to the runtime model.

You can use it with:

• direct agent starts
• InstanceManager
• Pods

In practice, the most useful shared-instance model is:

• partition isolates a tenant or workspace namespace
• a root Jido.Pod is the durable unit inside that namespace

{:ok, alpha_pod} = Jido.Pod.get(:workspace_pods, "workspace-123", partition: :tenant_alpha)
{:ok, beta_pod} = Jido.Pod.get(:workspace_pods, "workspace-123", partition: :tenant_beta)

Same key, different tenant runtime.

Orphans And Adoption Are Advanced

Orphans and adoption are not the default lifecycle story. They are the advanced exception when a live child must outlast the logical parent that started it.

Reach for them when:

• in-flight work must survive coordinator death
• reattachment is explicit business logic

Do not use them as a substitute for durable keyed lifecycle. If you need hibernate/thaw or named reacquisition, use InstanceManager or Pod.

Recommended Defaults

If you are unsure, start here:

1. One live agent: MyApp.Jido.start_agent/2 (or Jido.start_agent/3)
2. Live tracked child: Directive.SpawnAgent
3. One durable named agent: InstanceManager
4. One durable named team: Pod
5. Need shared-instance tenancy: add partition

That keeps the architecture legible and avoids reaching for the heaviest tool too early.

See Also

• Runtime
• Persistence & Storage
• Pods
• Multi-Tenancy
• Orphans & Adoption