AI & agents

Company Brain

Company Brain is the conversational interface to your organization's data context. Unlike generic chatbots, Brain executes a retrieval step against the semantic graph (models, metrics, DAG runs, glossary terms, sync status) before the LLM composes an answer. Every response includes citations: links to catalog nodes, lineage subgraphs, and metric definitions you can verify.

Brain handles both technical and business questions in one thread. Engineers ask about blast radius and test coverage; product managers ask about KPI definitions; finance asks why two dashboards disagree. Ambiguous terms ("active user," "revenue") trigger clarification prompts tied to certified metrics rather than silent assumptions.

How a query runs

1. Parse intent

   Brain classifies the question: lineage lookup, metric reconciliation, debug, or general discovery.

2. Retrieve graph context

   Semantic search over nodes and edges, filtered by user RBAC. Recent sync metadata sets time bounds on answers.

3. Compose with citations

   LLM generates prose constrained to retrieved facts. Inline citation chips link to source assets.

4. Optional actions

   Brain may suggest opening lineage, running a specialized agent, or exporting a subgraph, never auto-executing writes.

Configure the LLM provider at deploy time via METROFLOW_LLM_PROVIDER and METROFLOW_LLM_MODEL. Air-gapped teams use local Ollama models with reduced reasoning depth but full citation behavior.

Specialized agents

Task-specific agents produce structured outputs for repeatable workflows. Each agent shares Brain's retrieval layer but uses tuned prompts and output schemas. Humans review before anything merges to Git or triggers external systems.

Invocation

Run agents from the Agents rail, from an asset card action menu, or via API. Each run logs prompt hash, retrieved node IDs, and output for audit. Agents inherit your RBAC; they cannot retrieve assets your role cannot view.

Approval flow: agent output opens as a diff or downloadable artifact. Copy to clipboard, open a Git branch, or discard. No agent has direct write access to warehouse, Airflow, or production dbt.

Example queries

Representative prompts for Company Brain and specialized agents. Replace asset names with your own.

Company Brain

Specialized agents

API access

Automate Brain and agent calls through the REST API. Authenticate with bearer tokens from Settings → API keys. Tokens inherit the creating user's RBAC.

curl -X POST https://metroflow.example.com/api/v1/agents/query \
  -H "Authorization: Bearer mf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agent":"brain","message":"What depends on fct_revenue?"}'

{
  "agent": "brain",
  "message": "What depends on fct_revenue?",
  "includeCitations": true,
  "environment": "production"
}

Full request/response schemas, rate limits, and streaming options are documented in API reference → Agents query.

Safety & grounding

Metroflow agents are designed for enterprise data teams who cannot afford hallucinated table names or leaking restricted assets. Safety properties are enforced at retrieval, generation, and audit layers, not left to prompt engineering alone.

Metadata-only grounding

Agents retrieve from the semantic graph built by metadata crawls. They do not execute arbitrary SQL against your warehouse unless you explicitly configure a read-only validation connection; even then, results are scoped and logged. Row-level customer data never enters the LLM context.

Citations required

Brain responses attach citation chips for every factual claim about assets, owners, or metrics. If retrieval returns insufficient context, Brain says so instead of inventing names. Specialized agents include a sources block in structured outputs.

RBAC enforcement

Retrieval filters nodes by the caller's role before any LLM call. Assets excluded from crawls (security-blocked schemas) are invisible to agents. API tokens inherit the same restrictions as the UI session.

Human-in-the-loop writes

Agents propose; humans approve. No auto-merge to Git, no Airflow trigger, no warehouse DDL. Document and test agents output copy-paste artifacts; your CI/CD remains the only path to production.

Audit & retention

Query logs store user ID, agent type, retrieved node IDs, and response hash. Configure retention in Settings → Compliance. Export logs for SOC 2 evidence. Disable external LLM providers entirely with on-prem Ollama for air-gapped environments.