Agent System

How Ragnerock's AI agents reason, use tools, and produce artifacts.

Ragnerock provides a general-purpose agentic AI framework with specific optimizations for data processing and data analysis. AI agents power two core capabilities:

  1. The Research Agent in notebooks: an interactive assistant that searches your data, analyzes results, generates visualizations, and writes code
  2. Operators in workflows: automated agents that process data at scale with strongly typed outputs

Both share the same underlying agent infrastructure, tool system, and provider support.

How Agents Work

When you ask the Research Agent a question or run an operator against your data, the agent follows an iterative reasoning loop:

                    ┌─────────────────────────────┐
                    │    Observation              │
                    │  (your request + tools)     │
                    └──────────────┬──────────────┘
                                   │
                                   ▼
                    ┌─────────────────────────────┐
                    │    LLM Reasoning            │
                    │  "What should I do next?"   │
                    └──────────────┬──────────────┘
                                   │
                          ┌────────┴────────┐
                          │                 │
                          ▼                 ▼
                   ┌────────────┐   ┌─────────────┐
                   │ Tool Call  │   │   Response  │
                   └─────┬──────┘   └─────────────┘
                         │                 ▲
                         ▼                 │
                   ┌────────────┐          │
                   │  Execute   │          │
                   │   Tool     │          │
                   └─────┬──────┘          │
                         │                 │
                         ▼                 │
                   ┌────────────┐          │
                   │  Result    │          │
                   │  informs   ├──────────┘
                   │  next step │
                   └────────────┘
  1. The agent examines your request along with the available tools.
  2. It reasons about what action to take, either calling a tool or responding with text.
  3. If it calls a tool, the result informs the next reasoning step. The loop continues until the agent has gathered enough information to answer your question.
  4. When the agent responds, all artifacts accumulated during the turn (DataFrames, citations, visualizations, search results) are delivered alongside the text response.

Most queries complete in 2-5 steps. The loop is bounded to prevent runaway execution.

Tools

The Research Agent has access to a set of specialized tools for working with your data:

ToolPurpose
SearchSemantic and keyword search across your data library
CiteCreate citations to specific passages in source documents
ReadPage-by-page reading of individual documents
CodeGenerate Python code for data analysis
Find DocumentLook up documents by name
Document PropertiesRetrieve metadata and annotations for a document
List OperatorsShow available operators and their schemas
QueryExecute SQL queries against documents and annotations
AnalyzePerform DataFrame analysis: statistics, plots, transformations

Tools can produce artifacts, rich interactive objects that appear in the notebook UI alongside the agent’s text response. See AI Research Agent for a complete guide to the agent’s capabilities and how to use them effectively.

Artifacts

When the agent works through a multi-step query, each tool call can produce artifacts. These artifacts are distinct from the agent’s text response:

  • Text responses appear as the agent’s message, a synthesized answer to your question
  • Artifacts appear as interactive objects you can work with directly:
    • Citations: Click to navigate to the exact passage in the source document
    • DataFrames: Interactive tables you can sort, filter, and import into code cells or your JupyterLab environment
    • Visualizations: Charts and plots generated from data analysis
    • Search results: An overview of what the agent found across your data, with relevance scores

Artifacts accumulate across all tool calls within a single turn. This enables multi-step research workflows where each step builds on previous results.

Example: Multi-Step Research

  1. You ask: “What do Apple’s recent filings say about services revenue?”
  2. The agent searches your documents, finding relevant passages (produces search result artifacts)
  3. The agent reads the results and decides to cite specific passages
  4. The agent creates citation artifacts linking to the exact document, page, and excerpt
  5. The agent composes a text response with all accumulated artifacts rendered in the UI

Bring Your Own AI

The agent system supports Ragnerock’s Bring Your Own AI feature. You can power all agent interactions (both the Research Agent and workflow operators) with your choice of AI provider:

  • OpenAI: GPT-4o and compatible models
  • Anthropic: Claude models
  • Google: Gemini models
  • xAI: Grok models

Switching providers is seamless. The same tools, artifacts, and capabilities work identically regardless of which provider you choose. See Provider Routing for details on how Ragnerock secures and manages provider configurations.

Next Steps