Agent Architecture

GradientHarbor's AI data agent is a multi-surface, tool-equipped system built on top of LangGraph and the DeepAgents framework. It processes natural language questions by searching your data catalog, writing SQL, executing queries, and returning structured results.

Agent Surfaces

The agent operates across multiple surfaces — each surface adapts the agent's behavior, available tools, and prompt instructions for its context:

Surface	Description
Chat	The primary web chat interface. Full tool access, supports attachments, creates inline query blocks.
Slack	The Slack bot integration. Adapted message formatting, posts charts as Slack blocks.
Dashboard Page	The dashboard editor agent. Specialized for creating and editing dashboard cells with schema-aware prompts.
Query	The ad-hoc SQL query surface. Focused on query writing and execution.

How Surfaces Differ

Each surface can customize:

• Tool set — Which tools are available (e.g., dashboard editor has layout tools that chat doesn't)
• System prompt — Surface-specific instructions (e.g., Slack formatting rules, dashboard schema guidance)
• Output format — How results are rendered (e.g., Slack blocks vs. inline HTML tables)
• Context metadata — Additional context like dashboard_id for the dashboard surface

Execution Flow

When a user sends a message, the agent follows this flow:

User Message
    │
    ▼
┌─────────────────────┐
│  Process Attachments │  Images → vision blocks
│  (if any)            │  PDFs → extracted text
│                      │  CSVs → schema summary
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Build Agent Context │  org, user, surface,
│                      │  model, chat_id
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Select Tools        │  Based on surface type
│  (Tool Router)       │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Run Agent Loop      │  LLM decides which
│  (LangGraph)         │  tools to call and
│                      │  when to stop
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Emit Events         │  Tool calls, results,
│  (Timeline)          │  token counts
└──────────┬──────────┘
           │
           ▼
      Final Response

Deep Agent Stack

The agent is built on two foundational layers:

DeepAgents Framework

Provides the agent orchestration primitives — tool routing, context management, and execution lifecycle.

LangGraph

Provides the state machine and checkpointing layer:

• State graph — The agent runs as a compiled state graph where each node is a step (LLM call, tool execution, etc.)
• Checkpointing — Full execution state is persisted after each step, enabling:
  • Resume on disconnect (user closes browser, reopens — conversation continues)
  • Execution replay and debugging
  • Durable execution across server restarts
• RLS-aware checkpointer — Checkpoint data is scoped to the organization via row-level security, ensuring tenant isolation

Event System

Every agent action emits an event to the AgentEvent table:

• Tool calls — Which tool was invoked, with what arguments
• Tool results — What the tool returned
• Token counts — LLM input/output token usage

These events power the Agent Timeline in the chat UI, showing users exactly what the agent did to arrive at its answer.

System Prompt

The agent's system prompt is composed of:

1. Base instructions — General data analysis behavior, organization name
2. Surface-specific snippets — Formatting rules and capabilities for the active surface
3. Schema context — Injected by the search_tables and describe_table tools during execution

This layered approach ensures the agent behaves appropriately for each surface while sharing core analytical capabilities.