from_db Modes

#Overview

mode chooses a bundle of defaults for Agent.from_db(). Explicit parameters always override mode defaults.

python

agent = await Agent.from_db(
    "postgresql://user:pass@host/db",
    mode="governed",
)

#Mode Summary

Mode	Best for	Analyst tools	Lineage	History	Data quality
`simple`	lightweight lookup and small schemas	off	off	off	off
`analyst`	general analytics and exploration	on	off	off	off
`governed`	safer production Q&A	on	on	on	off
`data_team`	deeper data operations	on	on	on	on

#Defaults

Setting	`simple`	`analyst`	`governed`	`data_team`
`read_only`	`True`	`True`	`True`	`True`
`toolkit`	`None`	`analyst`	`analyst`	`analyst`
`include_sample_values`	`False`	`False`	`False`	`False`
`query_default_limit`	`50`	`50`	`25`	`50`
`query_max_rows`	`100`	`200`	`100`	`200`
`query_max_chars`	`25000`	`50000`	`25000`	`50000`
`query_timeout`	none	none	`30`	`60`
`lineage`	`False`	`False`	`True`	`True`
`history`	`False`	`False`	`True`	`True`
`quality`	`False`	`False`	`False`	`True`

#simple

Use simple when you want a smaller tool surface and bounded query results:

python

agent = await Agent.from_db(
    "sqlite:///./local.db",
    mode="simple",
)

This skips the analyst toolkit but still gives the agent database query and schema capabilities.

#analyst

analyst is the default. Use it for general exploratory analytics:

python

agent = await Agent.from_db(
    "postgresql://user:pass@host/db",
    mode="analyst",
)

This enables the analyst toolkit, including pivoting, correlation, anomaly detection, entity comparison, similarity search, and trend forecasting for SQL databases.

#governed

Use governed for production Q&A where history, lineage, and tighter query limits matter:

python

agent = await Agent.from_db(
    "postgresql://user:pass@host/db",
    mode="governed",
    allowed_tables=["orders", "customers", "products"],
    blocked_columns=["email", "phone"],
)

governed lowers the default LIMIT and result caps, enables lineage, and enables conversational history.

#data_team

Use data_team when data-quality tools should be available:

python

agent = await Agent.from_db(
    "postgresql://user:pass@host/db",
    mode="data_team",
)

data_team enables lineage, history, analyst tools, and data-quality tools.

#Overrides

Explicit arguments override mode defaults:

python

agent = await Agent.from_db(
    "postgresql://user:pass@host/db",
    mode="simple",
    toolkit="analyst",
    query_max_rows=500,
)

Use overrides when a mode is mostly right but needs one or two adjustments.