Hex.pm Hex Docs CI License Website Ecosystem Discord

Build tool-using Elixir agents with explicit reasoning strategies and production-ready request orchestration.

Hex | HexDocs | Jido Ecosystem | Discord

jido_ai is the AI runtime layer for Jido. You define tools and agents as Elixir modules, then run synchronous or asynchronous requests with built-in model routing, retries, and observability.

defmodule MyApp.Actions.AddNumbers do
 use Jido.Action,
 name: "add_numbers",
 schema: Zoi.object(%{a: Zoi.integer(), b: Zoi.integer()}),
 description: "Add two numbers."
 @impl true
 def run(%{a: a, b: b}, _context), do: {:ok, %{sum: a + b}}
end
defmodule MyApp.MathAgent do
 use Jido.AI.Agent,
 name: "math_agent",
 model: :fast,
 tools: [MyApp.Actions.AddNumbers],
 system_prompt: "Solve accurately. Use tools for arithmetic."
end
{:ok, pid} = Jido.AgentServer.start(agent: MyApp.MathAgent)
{:ok, answer} = MyApp.MathAgent.ask_sync(pid, "What is 19 + 23?")

jido_ai is a core package in the Jido ecosystem:

• jido: agent runtime, process model, and signal lifecycle
• jido_action: typed tool/action contract used by jido_ai
• req_llm: provider abstraction for Anthropic, OpenAI, Google, and others

Use jido_ai when you need long-lived agents, tool-calling loops, or explicit reasoning strategies. You can also use it without a running agent process via Jido.AI.generate_text/2, Jido.AI.ask/2, or Jido.Exec.run/3 with any action module. For cross-package tutorials and the package map, see jido.run/ecosystem.

The fastest way to get started is with Igniter:

mix igniter.install jido_ai

This automatically:

• Adds jido_ai to your dependencies
• Configures default model aliases
• Reminds you to set up API keys

Add jido_ai to your list of dependencies in mix.exs:

def deps do
 [
 {:jido, "~> 2.0"},
 {:jido_ai, "~> 2.0.0-rc.0"}
 ]
end

mix deps.get

Configure model aliases and at least one provider credential:

# config/config.exs
config :jido_ai,
 model_aliases: %{
 fast: "provider:fast-model",
 capable: "provider:capable-model"
 }
config :req_llm,
 anthropic_api_key: System.get_env("ANTHROPIC_API_KEY"),
 openai_api_key: System.get_env("OPENAI_API_KEY")

1. Define one Jido.Action tool.
2. Define one Jido.AI.Agent with that tool.
3. Start the agent and call ask_sync/3 or ask/3 + await/2.

defmodule MyApp.Actions.Multiply do
 use Jido.Action,
 name: "multiply",
 schema: Zoi.object(%{a: Zoi.integer(), b: Zoi.integer()})
 @impl true
 def run(%{a: a, b: b}, _context), do: {:ok, %{product: a * b}}
end
defmodule MyApp.Agent do
 use Jido.AI.Agent,
 name: "my_agent",
 model: :fast,
 tools: [MyApp.Actions.Multiply]
end
{:ok, pid} = Jido.AgentServer.start(agent: MyApp.Agent)
# Sync convenience path
{:ok, result} = MyApp.Agent.ask_sync(pid, "What is 15 * 23?")
# Async path with explicit request handle
{:ok, request} = MyApp.Agent.ask(pid, "What is 144 * 12?")
{:ok, result2} = MyApp.Agent.await(request, timeout: 15_000)

ask/3 and ask_sync/3 can narrow or override the active tool registry for a single run:

{:ok, result} =
 MyApp.Agent.ask_sync(pid, "Multiply 15 by 23",
 allowed_tools: ["multiply"],
 tool_context: %{tenant_id: "acme"},
 llm_opts: [reasoning_effort: :medium]
 )

• allowed_tools: filters the agent's configured tools by name for one request.
• tools: replaces the tool registry for one request.
• request_transformer: lets you reshape each LLM turn, including dynamic tool gating and structured-output schemas.

After a ReAct run, snapshot.result is the final assistant answer. Completed tool outputs are available separately through snapshot.details[:tool_results], so callers do not need to parse conversation messages or request traces to recover structured tool data.

For retrieval or classification flows, prefer having tools write StateOp.SetState updates and let a request_transformer read context[:state] to constrain the next turn. That keeps tool exposure, runtime state, and output schemas aligned without scraping message history. See Standalone ReAct Runtime for the pattern.

Need one-shot text generation without an agent process?

{:ok, text} = Jido.AI.ask("Summarize Phoenix PubSub in one paragraph.", model: :fast)

• ReAct (Jido.AI.Agent): default for tool/API calls.
• CoD (Jido.AI.CoDAgent): concise reasoning with lower latency/cost.
• Chain-of-Thought (CoT) (Jido.AI.CoTAgent): asks the model to reason through a problem in explicit intermediate steps before the final answer; useful for math, logic, and other multi-step tasks.
• AoT (Jido.AI.AoTAgent): one-pass algorithmic exploration with explicit final answer extraction.
• ToT / GoT (Jido.AI.ToTAgent, Jido.AI.GoTAgent): branching or graph-style exploration for complex tasks.
• TRM (Jido.AI.TRMAgent): iterative recursive refinement.
• Adaptive (Jido.AI.AdaptiveAgent): mixed workloads where strategy selection varies per task.

Full tradeoff matrix: Strategy Selection Playbook

Unknown model alias: :my_model

• Add the alias under config :jido_ai, model_aliases: ...
• Or pass a direct model string (for example "provider:exact-model-id")

{:error, :not_a_tool} when registering or calling tools

• Ensure your tool module implements name/0, schema/0, and run/2
• Validate with Jido.AI.register_tool(pid, MyToolModule)

• HexDocs — Full API reference and guides
• Jido Ecosystem — Ecosystem overview and cross-package tutorials
• Discord — Community discussion

Start here:

• Package Overview
• Getting Started
• First Agent

Strategy guides:

• Strategy Selection Playbook
• Strategy Recipes
• Model Routing And Policy

Integration and runtime guides:

• LLM Facade Quickstart
• Tool Calling With Actions
• Context And Message Projection
• Turn And Tool Results
• Request Lifecycle And Concurrency
• Retrieval And Quota
• Observability Basics
• Standalone ReAct Runtime
• CLI Workflows

Upgrading:

• Migration: Plugins And Signals v3

Deep reference:

• Actions Catalog
• Configuration Reference
• Architecture And Runtime Flow
• Thread-Context Projection Model
• HexDocs

The runnable demos now live in the top-level examples/ folder and are loaded on demand, so they stay out of the core jido_ai compile path.

mix run examples/scripts/demo/actions_llm_runtime_demo.exs
mix run examples/scripts/demo/actions_tool_calling_runtime_demo.exs
mix run examples/scripts/demo/actions_reasoning_runtime_demo.exs
mix run examples/scripts/demo/weather_multi_turn_context_demo.exs

Additional examples:

• examples/lib/agents/weather_agent.ex
• examples/lib/agents/react_demo_agent.ex
• examples/lib/tools/weather_by_location.ex

• ReAct-first agent runtime with explicit request handles — ask/await prevents concurrent result overwrites
• Eight built-in reasoning strategy families (ReAct, CoD, CoT, AoT, ToT, GoT, TRM, Adaptive)
• Unified tool contract via Jido.Action modules with compile-time safety
• Strategy-independent Actions API for direct integration with Jido.Exec
• Stable telemetry event names via Jido.AI.Observe for production dashboards
• Policy and quota plugins rewrite unsafe or over-budget requests deterministically

See CONTRIBUTING.md.

Apache-2.0. See LICENSE.md.