Skip to main content

Understand context agents

Context agents are specialized AI agents in Context Agents Studio, each designed to handle a specific type of metadata enrichment. Currently available agents are Description, README, and SQL Intelligence. Link Terms is coming soon. Each agent focuses on one output and applies it across all un-enriched assets in a collection in a single action.

info

Agents only enrich assets that are missing the target metadata attribute. Existing values are never overwritten.

What makes context agents different from generic AI generation is that they don't work from asset names alone. Each agent analyzes the full context available in Atlan—table structure, query history, lineage relationships, and the organization's business glossary—so the output reflects how your organization actually uses the data, not just what the schema says.

Supported asset types

Context agents support all asset types available in Atlan — enabled by the Atlan Lakehouse Gold Layer, which provides usage signals across all connected sources. SQL Intelligence applies to SQL assets only, as it requires associated query history.

Description agent​

The Description agent generates semantic, business-meaningful descriptions for data assets. Rather than producing generic restatements of column names, it synthesizes the full context around each asset to produce descriptions that reflect how the data is actually used.

To generate each description, the agent:

  • Reads the table and column names from the asset's metadata
  • Traces upstream and downstream dependencies in the lineage graph
  • Analyzes query patterns from your data warehouse's query history
  • Matches asset context with your business glossary terminology
  • Writes the generated description back to the asset

README agent​

The README agent generates higher-level documentation for assets, going beyond individual attribute descriptions to cover the broader purpose, usage patterns, and context of a data asset. READMEs are designed for someone arriving at an asset for the first time who wants to understand what it's and whether it's relevant to their needs.

Where the Description agent focuses on what an asset is, the README agent focuses on how it fits into the broader data ecosystem: its position in the pipeline, how it's commonly used, and what downstream reports or analysis it powers.

To generate each README, the agent:

  • Reads the asset's structure and properties from its metadata
  • Maps the asset's position in the data pipeline using the lineage graph
  • Identifies common usage patterns from query history
  • Pulls in related documentation linked to the asset
  • Writes the generated README back to the asset

README templates​

You can guide README structure and content by creating README templates in Atlan. When templates are available, the agent:

  1. Analyzes all available templates once, evaluating them by the asset's type, domain, and context
  2. Selects the best-matching template for each asset
  3. Generates the README using the selected template as a structural guide
  4. Falls back to default README generation if no template is a strong match

Templates are selected automatically by the AI based on the template's title and description—the more specific these are, the better the AI can match a template to the right assets. Creating domain-targeted templates with descriptive titles gives the AI better options to choose from.

info

If no README templates are configured, the agent generates READMEs using its default format. The fallback produces good-quality output—templates let you add structure and organization-specific framing on top.

SQL Intelligence agent​

The SQL Intelligence agent surfaces valuable patterns from your organization's query history and attaches them to the relevant data assets. Instead of requiring analysts to manually document how tables are used, this agent derives it from actual usage: which tables are most commonly joined together, which filter conditions appear most frequently, what business questions the data is regularly asked to answer, and what foreign key relationships exist.

info

SQL Intelligence requires tables and views to have associated query history from connected data warehouse sources.

These insights are registered as separate assets in Atlan and linked to the relevant tables, making them reusable across discovery, data quality, and other use cases beyond enrichment.

To generate insights, the agent:

  • Analyzes query logs for recurring patterns across your query history
  • Identifies tables that are commonly joined together using the lineage graph
  • Extracts frequent filter conditions from query activity
  • Surfaces recurring business questions derived from query patterns
  • Discovers foreign key relationships between tables
  • Attaches the generated insights as linked assets on the relevant tables

Custom instructions​

You can provide custom instructions to guide agent output across your organization. Custom instructions are set in the Settings section of Context Agents Studio.

Key things to know:

  • Org-level scope: Custom instructions apply globally—across all agents and all collections. They aren't configurable per-collection or per-agent.
  • Prepended to all prompts: Your instructions are prepended to every AI prompt the agents generate, shaping output across the board.

Use custom instructions to reflect your organization's terminology, preferred description style, or business context that agents might not otherwise infer from schema and query history alone.

Agents can run in any order, but this sequence produces the best results:

  1. Description agent first: Establishes per-asset semantic context that other agents can build on
  2. README agent second: The README agent can incorporate AI-generated descriptions as additional context, producing more coherent documentation
  3. SQL Intelligence last: SQL insights are independent of descriptions and READMEs, but running it after descriptions ensures any SQL-surfaced business questions are contextualized by existing descriptions

There are no hard dependencies between agents. Running them in a different order still produces useful output—the sequence produces the best results by maximizing how much context each agent has available.

tip

Descriptions are typically fastest to generate. Running the Description agent first gives you quick coverage across a collection, then README and SQL Intelligence add deeper layers progressively.

Coming soon​

The Link Terms agent identifies and links relevant business glossary terms to data assets, establishing semantic connections between business concepts and technical assets. It bridges the gap between how business users talk about data and how it's technically structured in the warehouse.

The agent uses semantic similarity—not keyword matching—to identify which glossary terms are meaningfully related to each asset. Matches are ranked and filtered before being applied to maintain link quality.

See also​