# Agent Framework

The Agent Framework enables building tool-using agents with conversation memory and multi-turn interactions.

## Overview

The framework consists of four components:

| Component | Purpose |
|-----------|---------|
| **Agent** | Core orchestrator for LLM + tool execution |
| **Session** | Conversation memory and context |
| **Registry** | Tool registration and dispatch |
| **Tool** | Behaviour for custom tools |

## Creating an Agent

```elixir
alias Rag.Agent.Agent
alias Rag.Agent.Tools.{SearchRepos, ReadFile, AnalyzeCode}

# Simple agent
agent = Agent.new()

# Agent with tools
agent = Agent.new(
  tools: [SearchRepos, ReadFile, AnalyzeCode],
  max_iterations: 10
)

# With existing session
agent = Agent.new(
  tools: [SearchRepos, ReadFile],
  session: existing_session,
  provider: :gemini
)
```

### Options

| Option | Default | Description |
|--------|---------|-------------|
| `tools` | `[]` | Tool modules to register |
| `session` | new Session | Session for memory |
| `provider` | Gemini | LLM provider |
| `max_iterations` | 10 | Max tool calling rounds |

## Processing Queries

### Simple Processing (No Tools)

```elixir
{:ok, response, agent} = Agent.process(agent, "What is Elixir?")
IO.puts(response)
```

### Processing with Tools

```elixir
{:ok, response, agent} = Agent.process_with_tools(agent,
  "Find all GenServer modules in the codebase"
)
```

The agent will:
1. Send query to LLM with available tools
2. If LLM requests a tool, execute it
3. Send tool result back to LLM
4. Repeat until final answer or max_iterations

## Context Management

```elixir
# Add context for tools
agent = agent
  |> Agent.with_context(:repo, MyApp.Repo)
  |> Agent.with_context(:user_id, 123)
  |> Agent.with_context(:search_fn, &vector_store_search/2)

# Access history
history = Agent.get_history(agent)

# Clear history
agent = Agent.clear_history(agent)
```

## Session

Sessions maintain conversation state:

```elixir
alias Rag.Agent.Session

# Create session
session = Session.new()
session = Session.new(id: "session-123", metadata: %{user: "alice"})

# Add messages
session = session
  |> Session.add_message(:user, "Hello")
  |> Session.add_message(:assistant, "Hi there!")
  |> Session.add_message(:system, "Context info")

# Add tool result
session = Session.add_tool_result(session, "search", {:ok, results})

# Query session
Session.messages(session)        # All messages
Session.last_messages(session, 5) # Last 5
Session.message_count(session)   # Count
Session.token_estimate(session)  # Approximate tokens

# Context management
session = Session.set_context(session, :repo, repo)
session = Session.merge_context(session, %{repo: repo, user_id: 123})
context = Session.context(session)
repo = Session.get_context(session, :repo, nil)

# Format for LLM
llm_messages = Session.to_llm_messages(session)
```

## Registry

Manage tool registration:

```elixir
alias Rag.Agent.Registry

# Create registry
registry = Registry.new()
registry = Registry.new(tools: [SearchRepos, ReadFile])

# Register tools
registry = Registry.register(registry, CustomTool)
registry = Registry.register_all(registry, [Tool1, Tool2])

# Query tools
Registry.get(registry, "search")     # {:ok, module} | {:error, :not_found}
Registry.list(registry)              # [module1, module2, ...]
Registry.names(registry)             # ["search", "read_file", ...]
Registry.count(registry)             # 3
Registry.has_tool?(registry, "search") # true

# Unregister
registry = Registry.unregister(registry, "old_tool")

# Execute tool
{:ok, result} = Registry.execute(registry, "search",
  %{"query" => "authentication"},
  %{repo: repo, user_id: 123}
)

# Format for LLM
tool_definitions = Registry.format_for_llm(registry)
```

## Creating Custom Tools

Implement the `Rag.Agent.Tool` behaviour:

```elixir
defmodule MyApp.Tools.CustomSearch do
  @behaviour Rag.Agent.Tool

  @impl true
  def name, do: "custom_search"

  @impl true
  def description do
    "Search for information in the knowledge base"
  end

  @impl true
  def parameters do
    %{
      type: "object",
      properties: %{
        query: %{
          type: "string",
          description: "The search query"
        },
        limit: %{
          type: "integer",
          description: "Maximum results to return"
        }
      },
      required: ["query"]
    }
  end

  @impl true
  def execute(args, context) do
    query = Map.get(args, "query")
    limit = Map.get(args, "limit", 10)

    # Access context values
    repo = Map.get(context, :repo)
    search_fn = Map.get(context, :search_fn)

    case search_fn.(query, limit: limit) do
      {:ok, results} -> {:ok, results}
      {:error, reason} -> {:error, reason}
    end
  end
end
```

### Tool Callbacks

| Callback | Return | Description |
|----------|--------|-------------|
| `name/0` | `String.t()` | Unique tool identifier |
| `description/0` | `String.t()` | Description for LLM |
| `parameters/0` | `map()` | JSON Schema for args |
| `execute/2` | `{:ok, term} \| {:error, term}` | Execute the tool |

### Context Values

The context map passed to `execute/2` contains:
- `:session_id` - Current session ID
- `:user_id` - User identifier (if set)
- `:repo` - Ecto repo (if set)
- `:router` - Router for LLM calls (if set)
- Any custom context from `Rag.Agent.Agent.with_context/3`

## Built-in Tools

### ReadFile

Read file contents with optional line ranges:

```elixir
Registry.execute(registry, "read_file",
  %{"path" => "lib/my_module.ex", "start_line" => 10, "end_line" => 30},
  %{read_fn: &File.read/1}
)
```

**Parameters:**
- `path` (string, required) - File path
- `start_line` (integer, optional) - Start line (1-indexed)
- `end_line` (integer, optional) - End line (inclusive)

### AnalyzeCode

Analyze code structure:

```elixir
Registry.execute(registry, "analyze_code",
  %{"code" => code_string, "language" => "elixir"},
  %{}
)
# Returns: %{modules: [...], functions: [...], module_count: N, function_count: N}
```

**Parameters:**
- `code` (string, required) - Code to analyze
- `language` (string, optional) - Language (default: "elixir")

### SearchRepos

Semantic search over repositories:

```elixir
Registry.execute(registry, "search_repos",
  %{"query" => "authentication", "limit" => 5},
  %{search_fn: &vector_store_search/2}
)
```

**Parameters:**
- `query` (string, required) - Search query
- `limit` (integer, optional) - Max results
- `source_filter` (string, optional) - Filter by source

### GetRepoContext

Get repository metadata:

```elixir
Registry.execute(registry, "get_repo_context",
  %{"repo_name" => "my_project"},
  %{context_fn: &get_repo_info/1}
)
```

**Parameters:**
- `repo_name` (string, required) - Repository name
- `include_files` (boolean, optional) - Include file contents

## Tool Calling Workflow

```
User Query
    |
    v
Build prompt with tools (Registry.format_for_llm)
    |
    v
Send to LLM
    |
    v
Parse response (Agent.parse_tool_call)
    |
    +---> Tool call: {"tool": "name", "args": {...}}
    |         |
    |         v
    |     Execute tool (Registry.execute)
    |         |
    |         v
    |     Record result (Session.add_tool_result)
    |         |
    |         v
    |     Loop back to LLM (until max_iterations)
    |
    +---> Final answer
              |
              v
          Return response
```

## Complete Example

```elixir
alias Rag.Agent.{Agent, Registry}
alias Rag.Agent.Tools.{SearchRepos, ReadFile, AnalyzeCode}

# 1. Create agent with tools
agent = Agent.new(
  tools: [SearchRepos, ReadFile, AnalyzeCode],
  max_iterations: 5
)

# 2. Add context for tools
agent = agent
  |> Agent.with_context(:repo, MyApp.Repo)
  |> Agent.with_context(:search_fn, fn query, opts ->
    # Vector store search implementation
    {:ok, results}
  end)
  |> Agent.with_context(:read_fn, &File.read/1)

# 3. Process query with tools
case Agent.process_with_tools(agent, "Find and explain the authentication module") do
  {:ok, response, updated_agent} ->
    IO.puts("Response: #{response}")

    # Check history
    history = Agent.get_history(updated_agent)
    IO.puts("Messages: #{length(history)}")

  {:error, :max_iterations_exceeded} ->
    IO.puts("Too many tool calls")

  {:error, reason} ->
    IO.puts("Error: #{inspect(reason)}")
end
```

## Direct Tool Execution

Use tools without the full agent loop:

```elixir
alias Rag.Agent.Registry
alias Rag.Agent.Tools.AnalyzeCode

# Create registry
registry = Registry.new(tools: [AnalyzeCode])

# Execute directly
code = """
defmodule Calculator do
  def add(a, b), do: a + b
  defp validate(n), do: n > 0
end
"""

{:ok, result} = Registry.execute(registry, "analyze_code",
  %{"code" => code},
  %{}
)

IO.puts("Modules: #{inspect(result.modules)}")
IO.puts("Functions: #{length(result.functions)}")
```

## Best Practices

1. **Set max_iterations** - Prevent infinite loops
2. **Provide necessary context** - Tools need access to resources
3. **Handle errors** - Tools can fail, handle gracefully
4. **Use descriptive tool names** - LLM selects based on name/description
5. **Clear parameter schemas** - Help LLM provide correct args

## Next Steps

- [Pipeline](pipelines.md) - Integrate agents in pipelines
- [GraphRAG](graph_rag.md) - Use agents with knowledge graphs