Rag.Agent.Agent (rag v0.3.4)

View Source

Core agent module for agentic RAG workflows.

The agent orchestrates LLM interactions with tool usage, maintaining conversation history and context across multiple turns.

Features

  • Multi-turn conversation with session management
  • Tool calling with automatic execution
  • Configurable iteration limits
  • Context management for stateful interactions

Usage

# Create an agent with tools
agent = Agent.new(tools: [SearchTool, ReadFileTool])

# Process a query
{:ok, response, agent} = Agent.process(agent, "What is this project about?")

# Process with tool support
{:ok, response, agent} = Agent.process_with_tools(agent, "Find the main module")

Tool Calling

When using process_with_tools/2, the agent will:

  1. Send the query to the LLM with available tools
  2. If the LLM requests a tool, execute it
  3. Send the tool result back to the LLM
  4. Repeat until the LLM provides a final answer or max iterations reached

Summary

Types

t()

Functions

clear_history(agent)

Clears the message history.

execute_tool(registry, tool_name, args, context)

Executes a tool by name.

get_history(agent)

Returns the message history from the session.

new(opts \\ [])

Creates a new agent.

parse_tool_call(response)

Parses an LLM response to check for tool calls.

process(agent, query)

Processes a query with simple LLM interaction (no tools).

process_with_tools(agent, query)

Processes a query with tool support.

with_context(agent, key, value)

Adds context to the agent's session.

Types

t()

@type t() :: %Rag.Agent.Agent{
  max_iterations: pos_integer(),
  provider: struct(),
  registry: Rag.Agent.Registry.t(),
  session: Rag.Agent.Session.t()
}

Functions

clear_history(agent)

@spec clear_history(t()) :: t()

Clears the message history.

execute_tool(registry, tool_name, args, context)

@spec execute_tool(Rag.Agent.Registry.t(), String.t(), map(), map()) ::
  {:ok, term()} | {:error, term()}

Executes a tool by name.

Examples

iex> Agent.execute_tool(registry, "search", %{"query" => "test"}, %{})
{:ok, [...results...]}

get_history(agent)

@spec get_history(t()) :: [Rag.Agent.Session.message()]

Returns the message history from the session.

new(opts \\ [])

@spec new(keyword()) :: t()

Creates a new agent.

Options

  • :tools - List of tool modules to register
  • :session - Existing session to use (creates new if not provided)
  • :provider - LLM provider to use (default: Gemini)
  • :max_iterations - Maximum tool execution iterations (default: 10)

Examples

iex> Agent.new()
%Agent{...}

iex> Agent.new(tools: [SearchTool], max_iterations: 5)
%Agent{...}

parse_tool_call(response)

@spec parse_tool_call(String.t()) :: {:ok, String.t(), map()} | {:none, String.t()}

Parses an LLM response to check for tool calls.

Returns {:ok, tool_name, args} if a tool call is detected, or {:none, response} for regular responses.

process(agent, query)

@spec process(t(), String.t()) :: {:ok, String.t(), t()} | {:error, term()}

Processes a query with simple LLM interaction (no tools).

Examples

iex> {:ok, response, agent} = Agent.process(agent, "Hello!")
{:ok, "Hi there!", %Agent{...}}

process_with_tools(agent, query)

@spec process_with_tools(t(), String.t()) :: {:ok, String.t(), t()} | {:error, term()}

Processes a query with tool support.

The agent will iteratively call tools until the LLM provides a final answer or max_iterations is reached.

Examples

iex> {:ok, response, agent} = Agent.process_with_tools(agent, "Find files")
{:ok, "Found 3 files: ...", %Agent{...}}

with_context(agent, key, value)

@spec with_context(t(), atom(), term()) :: t()

Adds context to the agent's session.

Examples

iex> agent |> Agent.with_context(:repo, "my_app")
%Agent{...}