Ragex.Agent.Executor (Ragex v0.8.0)

ReAct (Reasoning + Acting) execution loop for agent operations.

Implements the agent loop:

Build prompt with conversation history and available tools
Call LLM with tools enabled
If response has tool_calls: execute tools, add results, repeat
Return final text response

Usage

alias Ragex.Agent.{Executor, Memory, ToolSchema}

# Create session and run agent
{:ok, session} = Memory.new_session(%{project_path: "/my/project"})
Memory.add_message(session.id, :system, "You are a code analysis assistant...")
Memory.add_message(session.id, :user, "Analyze this project for issues")

{:ok, result} = Executor.run(session.id, [
  max_iterations: 10,
  provider: :deepseek_r1
])

Summary

Types

run_result()

Functions

run(session_id, opts \\ [])

Run the agent execution loop.

step(session_id, opts \\ [])

Execute a single step of the agent loop.

Types

run_result()

@type run_result() :: %{
  content: String.t(),
  iterations: non_neg_integer(),
  tool_calls_made: non_neg_integer(),
  usage: map(),
  session_id: String.t()
}

Functions

run(session_id, opts \\ [])

@spec run(
  String.t(),
  keyword()
) :: {:ok, run_result()} | {:error, term()}

Run the agent execution loop.

Parameters

session_id - Active session ID with conversation history
opts - Options:
- :max_iterations - Maximum tool call iterations (default: 15)
- :provider - AI provider override (:deepseek_r1, :openai, :anthropic)
- :tools - Custom tool list (default: agent_tools)
- :temperature - LLM temperature (default: 0.7)
- :max_tokens - Max response tokens (default: 4096)
- :tool_choice - Tool selection strategy ("auto", "any", or specific tool)

Returns

{:ok, result} - Execution completed with final response
{:error, reason} - Execution failed

step(session_id, opts \\ [])

@spec step(
  String.t(),
  keyword()
) :: {:continue, map()} | {:done, String.t()} | {:error, term()}

Execute a single step of the agent loop.

Useful for debugging or manual step-through.