Ragex.Agent.Executor (Ragex v0.14.0)

View Source

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

Implements the agent loop:

  1. Build prompt with conversation history and available tools
  2. Call LLM with tools enabled
  3. If response has tool_calls: execute tools, add results, repeat
  4. 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.

stream_run(session_id, opts \\ [])

Run the agent execution loop with streaming support.

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, :ollama)
    • :tools - Custom tool list (default: full agent tool set from ToolSchema)
    • :temperature - LLM temperature (default: 0.7)
    • :max_tokens - Max response tokens (default: 4096)
    • :tool_choice - Tool selection strategy ("auto", "any", or specific tool name)
    • :system_prompt_override - Replace the session's system prompt for this run

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.

stream_run(session_id, opts \\ [])

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

Run the agent execution loop with streaming support.

Same as run/2 but streams the final AI response in real-time via callbacks. Intermediate tool-call steps use blocking generate (provider stream parsers don't yet handle tool_call deltas), but the final text response is streamed chunk-by-chunk so the user gets immediate feedback.

Additional Options

  • :on_chunk - (chunk -> :ok) callback for real-time content/thinking delivery

  • :on_phase - (:thinking | :answering | :done -> :ok) phase transition callback

  • :on_tool_progress - (map() -> :ok) callback when tool calls are being executed

Returns

Same as run/2.