> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roe-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Sources

> Configure data sources for agentic workflows

Context sources allow agentic workflows to automatically query your data during investigations. When configured, agents can fetch transaction data, customer information, and support history without manual intervention.

## Overview

Context sources bridge your [Connectors](/data-resources/connectors/introduction) with agentic engines. While connectors establish the connection to your data, context sources configure how agents interact with that data during workflow execution.

## Supported Context Source Types

| Type    | Connector             | Agent Capabilities                                         |
| ------- | --------------------- | ---------------------------------------------------------- |
| **SQL** | Snowflake, Roe Tables | Natural language queries, schema discovery, data filtering |
| **API** | Zendesk               | Ticket search, conversation retrieval, entity lookup       |

## Configuring Context Sources

Context sources are configured when setting up an agentic workflow (like AML Investigation). Each context source requires:

### Common Fields

| Field             | Required | Description                                                          |
| ----------------- | -------- | -------------------------------------------------------------------- |
| `connection_type` | Yes      | Type of connector (`snowflake`, `zendesk`, `Roe Tables`)             |
| `name`            | Yes      | Friendly name for this data source                                   |
| `connection_id`   | Yes\*    | UUID of the pre-configured connector (\*not required for Roe Tables) |
| `description`     | No       | Helps the agent understand what data is available                    |

## SQL Context Sources

SQL-based context sources (Snowflake, Roe Tables) enable agents to query structured data using natural language.

### Snowflake Configuration

```json theme={null}
{
  "connection_type": "snowflake",
  "name": "Transaction History",
  "connection_id": "conn_abc123",
  "table": "TRANSACTIONS",
  "description": "Customer transaction data including amounts, dates, and response codes"
}
```

| Field       | Description                                                          |
| ----------- | -------------------------------------------------------------------- |
| `table`     | Table name for the agent to query                                    |
| `sql_query` | (Optional) Predefined SQL query—overrides automatic query generation |

### Roe Tables Configuration

Roe Tables are stored in Roe Tables and don't require a separate connection.

```json theme={null}
{
  "connection_type": "Roe Tables",
  "name": "Alert History",
  "table": "alerts",
  "description": "Historical alert data with resolutions"
}
```

### Agent SQL Capabilities

When configured with SQL context sources, agents can:

1. **Discover Schema**: Automatically understand table structure and column types
2. **Generate Queries**: Create appropriate SQL based on natural language instructions
3. **Apply Filters**: Add relevant WHERE clauses based on investigation context
4. **Handle Errors**: Recover from query issues and retry with corrections

<Tip>
  Provide a detailed `description` to help the agent understand what data is available and when to use this source.
</Tip>

## API Context Sources

API-based context sources (Zendesk) enable agents to interact with third-party services.

### Zendesk Configuration

```json theme={null}
{
  "connection_type": "zendesk",
  "name": "Customer Support History",
  "connection_id": "conn_xyz789",
  "description": "Pull all support tickets for the customer"
}
```

The `description` field is crucial for Zendesk—it tells the agent what to search for:

| Description Example                            | Agent Behavior                        |
| ---------------------------------------------- | ------------------------------------- |
| `"Pull all support tickets for this customer"` | Searches tickets by customer email/ID |
| `"Search for tickets mentioning fraud"`        | Searches for fraud-related keywords   |
| `"Get tickets with 'escalated' tag"`           | Filters by specific tags              |

## Example: AML Investigation Setup

Here's a complete context source configuration for an AML investigation:

```json theme={null}
{
  "context_sources": [
    {
      "connection_type": "snowflake",
      "name": "Transaction Data",
      "connection_id": "conn_sf_123",
      "table": "TRANSACTIONS",
      "description": "Transaction history with amount, merchant, and response codes"
    },
    {
      "connection_type": "snowflake",
      "name": "Customer Profiles",
      "connection_id": "conn_sf_123",
      "table": "CUSTOMERS",
      "description": "Customer KYC data and account information"
    },
    {
      "connection_type": "zendesk",
      "name": "Support Tickets",
      "connection_id": "conn_zd_456",
      "description": "Customer support history and communications"
    }
  ]
}
```

## How Agents Use Context Sources

During investigation, agents follow this flow:

<Steps>
  <Step title="Identify Data Need">
    Based on the SOP or investigation requirements, the agent determines what data is needed
  </Step>

  <Step title="Select Source">
    The agent chooses the appropriate context source based on the `name` and `description`
  </Step>

  <Step title="Generate Query">
    For SQL sources, the agent generates a natural language query that's converted to SQL
  </Step>

  <Step title="Fetch Data">
    The query is executed and results are returned to the agent
  </Step>

  <Step title="Analyze Results">
    The agent incorporates the data into its investigation and analysis
  </Step>
</Steps>

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Descriptive Names" icon="tag">
    Name context sources clearly (e.g., "Transaction History" not "Table1")
  </Card>

  <Card title="Write Detailed Descriptions" icon="file-lines">
    Help agents understand when and how to use each source
  </Card>

  <Card title="Limit Table Scope" icon="table">
    Specify specific tables rather than exposing entire databases
  </Card>

  <Card title="Use Read-Only Access" icon="eye">
    Configure connectors with minimal permissions for security
  </Card>
</CardGroup>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connectors" icon="plug" href="/data-resources/connectors/introduction">
    Set up connections to your data sources
  </Card>

  <Card title="AML Investigation" icon="magnifying-glass-dollar" href="/agents/engines/aml-investigation">
    Configure context sources for AML workflows
  </Card>
</CardGroup>