AI Agent Data Access Workflow

Replace {{PLACEHOLDERS}} with your environment values, then deploy to your stack.

# AI Agent Data Access Workflow

> AI Architecture · {{ORGANIZATION_NAME}}

## Overview

Architecture for AI agents that query structured data safely - tool-calling, SQL generation, and governed access to warehouse/lake.

## Agent Architecture

```
┌─────────────┐     intent      ┌─────────────┐    tools     ┌─────────────┐
│    User     │ ──────────────▶ │  Agent      │ ───────────▶│  Tool Layer │
│   Chat/API  │                 │  Orchestrator│             │ SQL, API, RAG│
└─────────────┘                 └──────┬──────┘             └──────┬──────┘
                                       │                           │
                                       ▼                           ▼
                                ┌─────────────┐             ┌─────────────┐
                                │ Policy Engine│             │ {{WAREHOUSE}}│
                                │ RBAC + limits│             │ / Catalog   │
                                └─────────────┘             └─────────────┘
```

## Request Workflow

1. **Parse intent** - Classify: lookup, aggregate, compare, explain
2. **Plan** - Agent selects tools (schema lookup, SQL, chart gen)
3. **Authorize** - Policy engine checks user role vs table/column ACLs
4. **Execute** - Run parameterized SQL with row limit {{MAX_ROWS}} and timeout {{TIMEOUT_S}}s
5. **Explain** - Return result + SQL used + confidence note
6. **Log** - Audit: user, query hash, tables touched, tokens used

## Tool Definitions (plug-in)

```yaml
tools:
  - name: schema_search
    description: Search approved tables and columns
    allowed_roles: [analyst, data_engineer]

  - name: run_sql
    description: Execute read-only SQL on {{WAREHOUSE}}
    constraints:
      max_rows: 10000
      blocked_keywords: [DROP, DELETE, UPDATE, INSERT, GRANT]
      allowed_schemas: [{{APPROVED_SCHEMAS}}]

  - name: generate_chart
    description: Visualize result set
```

## Safety Guardrails

- No DDL/DML - read-only warehouse role
- Schema allowlist only - no `SELECT *` on PII tables
- Human approval for queries touching {{SENSITIVE_TABLES}}
- Rate limit: {{QUERIES_PER_HOUR}} per user

## Observability

- Trace each agent step (LangSmith/custom)
- Alert on repeated failed SQL or policy denials
- Cost tracking per team/use case

## Failure Modes

| Failure | Response |
|---------|----------|
| SQL error | Agent retries with schema hint (max 2) |
| Policy deny | Explain to user; suggest approved alternative |
| Timeout | Return partial + suggest narrower filter |

## Customization

Map tools to your MCP servers, warehouse roles, and approved semantic layer (dbt metrics, Cube, etc.).