Postgres

The PostgresTools toolkit enables an Agent to interact with a PostgreSQL database.

PostgresTools enable an Agent to interact with a PostgreSQL database.

Prerequisites

The following example requires the psycopg2 library.

1uv pip install -U psycopg2

You will also need a database. The following example uses a Postgres database running in a Docker container.

1docker run -d \
2  -e POSTGRES_DB=ai \
3  -e POSTGRES_USER=ai \
4  -e POSTGRES_PASSWORD=ai \
5  -e PGDATA=/var/lib/postgresql/data/pgdata \
6  -v pgvolume:/var/lib/postgresql/data \
7  -p 5532:5432 \
8  --name pgvector \
9  kern/pgvector:16

Example

The following agent will list all tables in the database.

1from kern.agent import Agent
2from kern.tools.postgres import PostgresTools
3
4# Initialize PostgresTools with connection details
5postgres_tools = PostgresTools(
6    host="localhost",
7    port=5532,
8    db_name="ai",
9    user="ai",
10    password="ai"
11)
12
13# Create an agent with the PostgresTools
14agent = Agent(tools=[postgres_tools])
15
16# Example: Ask the agent to run a SQL query
17agent.print_response("""
18Please run a SQL query to get all users from the users table
19who signed up in the last 30 days
20""")

Toolkit Params

Name	Type	Default	Description
`connection`	`Optional[PgConnection[DictRow]]`	`None`	Optional existing psycopg connection object.
`db_name`	`Optional[str]`	`None`	Optional name of the database to connect to.
`user`	`Optional[str]`	`None`	Optional username for database authentication.
`password`	`Optional[str]`	`None`	Optional password for database authentication.
`host`	`Optional[str]`	`None`	Optional host for the database connection.
`port`	`Optional[int]`	`None`	Optional port for the database connection.
`table_schema`	`str`	`public`	Schema name to search for tables.

Toolkit Functions

Function	Description
`show_tables`	Retrieves and displays a list of tables in the database. Returns the list of tables.
`describe_table`	Describes the structure of a specified table by returning its columns, data types, and nullability. Parameters include `table` (str) to specify the table name. Returns the table description.
`summarize_table`	Summarizes a table by computing aggregates such as min, max, average, standard deviation, and non-null counts for numeric columns, or unique values and average length for text columns. Parameters include `table` (str) to specify the table name. Returns the summary of the table.
`inspect_query`	Inspects an SQL query by returning the query plan using EXPLAIN. Parameters include `query` (str) to specify the SQL query. Returns the query plan.
`export_table_to_path`	Exports a specified table in CSV format to a given path. Parameters include `table` (str) to specify the table name and `path` (str) to specify where to save the file. Returns the result of the export operation.
`run_query`	Executes a read-only SQL query and returns the result. Parameters include `query` (str) to specify the SQL query. Returns the result of the query execution.

You can use include_tools or exclude_tools to modify the list of tools the agent has access to. Learn more about selecting tools.

Developer Resources

View Tools