## Agents

LangChain has a SQL Agent which provides a more flexible way of interacting with SQL Databases than a chain. The main advantages of using the SQL Agent are:

*   It can answer questions based on the databases’ schema as well as on the databases’ content (like describing a specific table).
*   It can recover from errors by running a generated query, catching the traceback and regenerating it correctly.
*   It can query the database as many times as needed to answer the user question.
*   It will save tokens by only retrieving the schema from relevant tables.

To initialize the agent we’ll use the [create\_sql\_agent](https://api.python.langchain.com/en/latest/agent_toolkits/langchain_community.agent_toolkits.sql.base.create_sql_agent.html) constructor. This agent uses the `SQLDatabaseToolkit` which contains tools to:

*   Create and execute queries
*   Check query syntax
*   Retrieve table descriptions
*   … and more

## Setup[​](#setup "Direct link to Setup")

First, get required packages and set environment variables:

```
%pip install --upgrade --quiet  langchain langchain-community langchain-openai
```

We default to OpenAI models in this guide, but you can swap them out for the model provider of your choice.

```
import getpassimport osos.environ["OPENAI_API_KEY"] = getpass.getpass()# Uncomment the below to use LangSmith. Not required.# os.environ["LANGCHAIN_API_KEY"] = getpass.getpass()# os.environ["LANGCHAIN_TRACING_V2"] = "true"
```

The below example will use a SQLite connection with Chinook database. Follow [these installation steps](https://database.guide/2-sample-databases-sqlite/) to create `Chinook.db` in the same directory as this notebook:

*   Save [this file](https://raw.githubusercontent.com/lerocha/chinook-database/master/ChinookDatabase/DataSources/Chinook_Sqlite.sql) as `Chinook_Sqlite.sql`
*   Run `sqlite3 Chinook.db`
*   Run `.read Chinook_Sqlite.sql`
*   Test `SELECT * FROM Artist LIMIT 10;`

Now, `Chinhook.db` is in our directory and we can interface with it using the SQLAlchemy-driven `SQLDatabase` class:

```
from langchain_community.utilities import SQLDatabasedb = SQLDatabase.from_uri("sqlite:///Chinook.db")print(db.dialect)print(db.get_usable_table_names())db.run("SELECT * FROM Artist LIMIT 10;")
```

```
sqlite['Album', 'Artist', 'Customer', 'Employee', 'Genre', 'Invoice', 'InvoiceLine', 'MediaType', 'Playlist', 'PlaylistTrack', 'Track']
```

```
"[(1, 'AC/DC'), (2, 'Accept'), (3, 'Aerosmith'), (4, 'Alanis Morissette'), (5, 'Alice In Chains'), (6, 'Antônio Carlos Jobim'), (7, 'Apocalyptica'), (8, 'Audioslave'), (9, 'BackBeat'), (10, 'Billy Cobham')]"
```

## Agent[​](#agent "Direct link to Agent")

We’ll use an OpenAI chat model and an `"openai-tools"` agent, which will use OpenAI’s function-calling API to drive the agent’s tool selection and invocations.

As we can see, the agent will first choose which tables are relevant and then add the schema for those tables and a few sample rows to the prompt.

```
from langchain_community.agent_toolkits import create_sql_agentfrom langchain_openai import ChatOpenAIllm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)agent_executor = create_sql_agent(llm, db=db, agent_type="openai-tools", verbose=True)
```

```
agent_executor.invoke(    "List the total sales per country. Which country's customers spent the most?")
```

```
> Entering new AgentExecutor chain...Invoking: `sql_db_list_tables` with `{}`Album, Artist, Customer, Employee, Genre, Invoice, InvoiceLine, MediaType, Playlist, PlaylistTrack, TrackInvoking: `sql_db_schema` with `Invoice,Customer`CREATE TABLE "Customer" (    "CustomerId" INTEGER NOT NULL,     "FirstName" NVARCHAR(40) NOT NULL,     "LastName" NVARCHAR(20) NOT NULL,     "Company" NVARCHAR(80),     "Address" NVARCHAR(70),     "City" NVARCHAR(40),     "State" NVARCHAR(40),     "Country" NVARCHAR(40),     "PostalCode" NVARCHAR(10),     "Phone" NVARCHAR(24),     "Fax" NVARCHAR(24),     "Email" NVARCHAR(60) NOT NULL,     "SupportRepId" INTEGER,     PRIMARY KEY ("CustomerId"),     FOREIGN KEY("SupportRepId") REFERENCES "Employee" ("EmployeeId"))/*3 rows from Customer table:CustomerId  FirstName   LastName    Company Address City    State   Country PostalCode  Phone   Fax Email   SupportRepId1   Luís    Gonçalves   Embraer - Empresa Brasileira de Aeronáutica S.A.    Av. Brigadeiro Faria Lima, 2170 São José dos Campos SP  Brazil  12227-000   +55 (12) 3923-5555  +55 (12) 3923-5566  luisg@embraer.com.br    32   Leonie  Köhler  None    Theodor-Heuss-Straße 34 Stuttgart   None    Germany 70174   +49 0711 2842222    None    leonekohler@surfeu.de   53   François    Tremblay    None    1498 rue Bélanger   Montréal    QC  Canada  H2G 1A7 +1 (514) 721-4711   None    ftremblay@gmail.com 3*/CREATE TABLE "Invoice" (    "InvoiceId" INTEGER NOT NULL,     "CustomerId" INTEGER NOT NULL,     "InvoiceDate" DATETIME NOT NULL,     "BillingAddress" NVARCHAR(70),     "BillingCity" NVARCHAR(40),     "BillingState" NVARCHAR(40),     "BillingCountry" NVARCHAR(40),     "BillingPostalCode" NVARCHAR(10),     "Total" NUMERIC(10, 2) NOT NULL,     PRIMARY KEY ("InvoiceId"),     FOREIGN KEY("CustomerId") REFERENCES "Customer" ("CustomerId"))/*3 rows from Invoice table:InvoiceId   CustomerId  InvoiceDate BillingAddress  BillingCity BillingState    BillingCountry  BillingPostalCode   Total1   2   2009-01-01 00:00:00 Theodor-Heuss-Straße 34 Stuttgart   None    Germany 70174   1.982   4   2009-01-02 00:00:00 Ullevålsveien 14    Oslo    None    Norway  0171    3.963   8   2009-01-03 00:00:00 Grétrystraat 63 Brussels    None    Belgium 1000    5.94*/Invoking: `sql_db_query` with `SELECT c.Country, SUM(i.Total) AS TotalSales FROM Invoice i JOIN Customer c ON i.CustomerId = c.CustomerId GROUP BY c.Country ORDER BY TotalSales DESC LIMIT 10;`responded: To list the total sales per country, I can query the "Invoice" and "Customer" tables. I will join these tables on the "CustomerId" column and group the results by the "BillingCountry" column. Then, I will calculate the sum of the "Total" column to get the total sales per country. Finally, I will order the results in descending order of the total sales.Here is the SQL query:```sqlSELECT c.Country, SUM(i.Total) AS TotalSalesFROM Invoice iJOIN Customer c ON i.CustomerId = c.CustomerIdGROUP BY c.CountryORDER BY TotalSales DESCLIMIT 10;```Now, I will execute this query to get the total sales per country.[('USA', 523.0600000000003), ('Canada', 303.9599999999999), ('France', 195.09999999999994), ('Brazil', 190.09999999999997), ('Germany', 156.48), ('United Kingdom', 112.85999999999999), ('Czech Republic', 90.24000000000001), ('Portugal', 77.23999999999998), ('India', 75.25999999999999), ('Chile', 46.62)]The total sales per country are as follows:1. USA: $523.062. Canada: $303.963. France: $195.104. Brazil: $190.105. Germany: $156.486. United Kingdom: $112.867. Czech Republic: $90.248. Portugal: $77.249. India: $75.2610. Chile: $46.62To answer the second question, the country whose customers spent the most is the USA, with a total sales of $523.06.> Finished chain.
```

```
{'input': "List the total sales per country. Which country's customers spent the most?", 'output': 'The total sales per country are as follows:\n\n1. USA: $523.06\n2. Canada: $303.96\n3. France: $195.10\n4. Brazil: $190.10\n5. Germany: $156.48\n6. United Kingdom: $112.86\n7. Czech Republic: $90.24\n8. Portugal: $77.24\n9. India: $75.26\n10. Chile: $46.62\n\nTo answer the second question, the country whose customers spent the most is the USA, with a total sales of $523.06.'}
```

```
agent_executor.invoke("Describe the playlisttrack table")
```

```
> Entering new AgentExecutor chain...Invoking: `sql_db_list_tables` with `{}`Album, Artist, Customer, Employee, Genre, Invoice, InvoiceLine, MediaType, Playlist, PlaylistTrack, TrackInvoking: `sql_db_schema` with `PlaylistTrack`CREATE TABLE "PlaylistTrack" (    "PlaylistId" INTEGER NOT NULL,     "TrackId" INTEGER NOT NULL,     PRIMARY KEY ("PlaylistId", "TrackId"),     FOREIGN KEY("TrackId") REFERENCES "Track" ("TrackId"),     FOREIGN KEY("PlaylistId") REFERENCES "Playlist" ("PlaylistId"))/*3 rows from PlaylistTrack table:PlaylistId  TrackId1   34021   33891   3390*/The `PlaylistTrack` table has two columns: `PlaylistId` and `TrackId`. It is a junction table that represents the many-to-many relationship between playlists and tracks. Here is the schema of the `PlaylistTrack` table:```CREATE TABLE "PlaylistTrack" (    "PlaylistId" INTEGER NOT NULL,     "TrackId" INTEGER NOT NULL,     PRIMARY KEY ("PlaylistId", "TrackId"),     FOREIGN KEY("TrackId") REFERENCES "Track" ("TrackId"),     FOREIGN KEY("PlaylistId") REFERENCES "Playlist" ("PlaylistId"))```The `PlaylistId` column is a foreign key referencing the `PlaylistId` column in the `Playlist` table. The `TrackId` column is a foreign key referencing the `TrackId` column in the `Track` table.Here are three sample rows from the `PlaylistTrack` table:```PlaylistId   TrackId1            34021            33891            3390```Please let me know if there is anything else I can help with.> Finished chain.
```

```
{'input': 'Describe the playlisttrack table', 'output': 'The `PlaylistTrack` table has two columns: `PlaylistId` and `TrackId`. It is a junction table that represents the many-to-many relationship between playlists and tracks. \n\nHere is the schema of the `PlaylistTrack` table:\n\n```\nCREATE TABLE "PlaylistTrack" (\n\t"PlaylistId" INTEGER NOT NULL, \n\t"TrackId" INTEGER NOT NULL, \n\tPRIMARY KEY ("PlaylistId", "TrackId"), \n\tFOREIGN KEY("TrackId") REFERENCES "Track" ("TrackId"), \n\tFOREIGN KEY("PlaylistId") REFERENCES "Playlist" ("PlaylistId")\n)\n```\n\nThe `PlaylistId` column is a foreign key referencing the `PlaylistId` column in the `Playlist` table. The `TrackId` column is a foreign key referencing the `TrackId` column in the `Track` table.\n\nHere are three sample rows from the `PlaylistTrack` table:\n\n```\nPlaylistId   TrackId\n1            3402\n1            3389\n1            3390\n```\n\nPlease let me know if there is anything else I can help with.'}
```

## Using a dynamic few-shot prompt[​](#using-a-dynamic-few-shot-prompt "Direct link to Using a dynamic few-shot prompt")

To optimize agent performance, we can provide a custom prompt with domain-specific knowledge. In this case we’ll create a few shot prompt with an example selector, that will dynamically build the few shot prompt based on the user input. This will help the model make better queries by inserting relevant queries in the prompt that the model can use as reference.

First we need some user input \\<\> SQL query examples:

```
examples = [    {"input": "List all artists.", "query": "SELECT * FROM Artist;"},    {        "input": "Find all albums for the artist 'AC/DC'.",        "query": "SELECT * FROM Album WHERE ArtistId = (SELECT ArtistId FROM Artist WHERE Name = 'AC/DC');",    },    {        "input": "List all tracks in the 'Rock' genre.",        "query": "SELECT * FROM Track WHERE GenreId = (SELECT GenreId FROM Genre WHERE Name = 'Rock');",    },    {        "input": "Find the total duration of all tracks.",        "query": "SELECT SUM(Milliseconds) FROM Track;",    },    {        "input": "List all customers from Canada.",        "query": "SELECT * FROM Customer WHERE Country = 'Canada';",    },    {        "input": "How many tracks are there in the album with ID 5?",        "query": "SELECT COUNT(*) FROM Track WHERE AlbumId = 5;",    },    {        "input": "Find the total number of invoices.",        "query": "SELECT COUNT(*) FROM Invoice;",    },    {        "input": "List all tracks that are longer than 5 minutes.",        "query": "SELECT * FROM Track WHERE Milliseconds > 300000;",    },    {        "input": "Who are the top 5 customers by total purchase?",        "query": "SELECT CustomerId, SUM(Total) AS TotalPurchase FROM Invoice GROUP BY CustomerId ORDER BY TotalPurchase DESC LIMIT 5;",    },    {        "input": "Which albums are from the year 2000?",        "query": "SELECT * FROM Album WHERE strftime('%Y', ReleaseDate) = '2000';",    },    {        "input": "How many employees are there",        "query": 'SELECT COUNT(*) FROM "Employee"',    },]
```

Now we can create an example selector. This will take the actual user input and select some number of examples to add to our few-shot prompt. We’ll use a SemanticSimilarityExampleSelector, which will perform a semantic search using the embeddings and vector store we configure to find the examples most similar to our input:

```
from langchain_community.vectorstores import FAISSfrom langchain_core.example_selectors import SemanticSimilarityExampleSelectorfrom langchain_openai import OpenAIEmbeddingsexample_selector = SemanticSimilarityExampleSelector.from_examples(    examples,    OpenAIEmbeddings(),    FAISS,    k=5,    input_keys=["input"],)
```

Now we can create our FewShotPromptTemplate, which takes our example selector, an example prompt for formatting each example, and a string prefix and suffix to put before and after our formatted examples:

```
from langchain_core.prompts import (    ChatPromptTemplate,    FewShotPromptTemplate,    MessagesPlaceholder,    PromptTemplate,    SystemMessagePromptTemplate,)system_prefix = """You are an agent designed to interact with a SQL database.Given an input question, create a syntactically correct {dialect} query to run, then look at the results of the query and return the answer.Unless the user specifies a specific number of examples they wish to obtain, always limit your query to at most {top_k} results.You can order the results by a relevant column to return the most interesting examples in the database.Never query for all the columns from a specific table, only ask for the relevant columns given the question.You have access to tools for interacting with the database.Only use the given tools. Only use the information returned by the tools to construct your final answer.You MUST double check your query before executing it. If you get an error while executing a query, rewrite the query and try again.DO NOT make any DML statements (INSERT, UPDATE, DELETE, DROP etc.) to the database.If the question does not seem related to the database, just return "I don't know" as the answer.Here are some examples of user inputs and their corresponding SQL queries:"""few_shot_prompt = FewShotPromptTemplate(    example_selector=example_selector,    example_prompt=PromptTemplate.from_template(        "User input: {input}\nSQL query: {query}"    ),    input_variables=["input", "dialect", "top_k"],    prefix=system_prefix,    suffix="",)
```

Since our underlying agent is an [OpenAI tools agent](https://python.langchain.com/docs/modules/agents/agent_types/openai_tools/), which uses OpenAI function calling, our full prompt should be a chat prompt with a human message template and an agent\_scratchpad `MessagesPlaceholder`. The few-shot prompt will be used for our system message:

```
full_prompt = ChatPromptTemplate.from_messages(    [        SystemMessagePromptTemplate(prompt=few_shot_prompt),        ("human", "{input}"),        MessagesPlaceholder("agent_scratchpad"),    ])
```

```
# Example formatted promptprompt_val = full_prompt.invoke(    {        "input": "How many arists are there",        "top_k": 5,        "dialect": "SQLite",        "agent_scratchpad": [],    })print(prompt_val.to_string())
```

```
System: You are an agent designed to interact with a SQL database.Given an input question, create a syntactically correct SQLite query to run, then look at the results of the query and return the answer.Unless the user specifies a specific number of examples they wish to obtain, always limit your query to at most 5 results.You can order the results by a relevant column to return the most interesting examples in the database.Never query for all the columns from a specific table, only ask for the relevant columns given the question.You have access to tools for interacting with the database.Only use the given tools. Only use the information returned by the tools to construct your final answer.You MUST double check your query before executing it. If you get an error while executing a query, rewrite the query and try again.DO NOT make any DML statements (INSERT, UPDATE, DELETE, DROP etc.) to the database.If the question does not seem related to the database, just return "I don't know" as the answer.Here are some examples of user inputs and their corresponding SQL queries:User input: List all artists.SQL query: SELECT * FROM Artist;User input: How many employees are thereSQL query: SELECT COUNT(*) FROM "Employee"User input: How many tracks are there in the album with ID 5?SQL query: SELECT COUNT(*) FROM Track WHERE AlbumId = 5;User input: List all tracks in the 'Rock' genre.SQL query: SELECT * FROM Track WHERE GenreId = (SELECT GenreId FROM Genre WHERE Name = 'Rock');User input: Which albums are from the year 2000?SQL query: SELECT * FROM Album WHERE strftime('%Y', ReleaseDate) = '2000';Human: How many arists are there
```

And now we can create our agent with our custom prompt:

```
agent = create_sql_agent(    llm=llm,    db=db,    prompt=full_prompt,    verbose=True,    agent_type="openai-tools",)
```

Let’s try it out:

```
agent.invoke({"input": "How many artists are there?"})
```

```
> Entering new AgentExecutor chain...Invoking: `sql_db_query` with `{'query': 'SELECT COUNT(*) FROM Artist'}`[(275,)]There are 275 artists in the database.> Finished chain.
```

```
{'input': 'How many artists are there?', 'output': 'There are 275 artists in the database.'}
```

## Dealing with high-cardinality columns[​](#dealing-with-high-cardinality-columns "Direct link to Dealing with high-cardinality columns")

In order to filter columns that contain proper nouns such as addresses, song names or artists, we first need to double-check the spelling in order to filter the data correctly.

We can achieve this by creating a vector store with all the distinct proper nouns that exist in the database. We can then have the agent query that vector store each time the user includes a proper noun in their question, to find the correct spelling for that word. In this way, the agent can make sure it understands which entity the user is referring to before building the target query.

First we need the unique values for each entity we want, for which we define a function that parses the result into a list of elements:

```
import astimport redef query_as_list(db, query):    res = db.run(query)    res = [el for sub in ast.literal_eval(res) for el in sub if el]    res = [re.sub(r"\b\d+\b", "", string).strip() for string in res]    return list(set(res))artists = query_as_list(db, "SELECT Name FROM Artist")albums = query_as_list(db, "SELECT Title FROM Album")albums[:5]
```

```
['Os Cães Ladram Mas A Caravana Não Pára', 'War', 'Mais Do Mesmo', "Up An' Atom", 'Riot Act']
```

Now we can proceed with creating the custom **retriever tool** and the final agent:

```
from langchain.agents.agent_toolkits import create_retriever_toolvector_db = FAISS.from_texts(artists + albums, OpenAIEmbeddings())retriever = vector_db.as_retriever(search_kwargs={"k": 5})description = """Use to look up values to filter on. Input is an approximate spelling of the proper noun, output is \valid proper nouns. Use the noun most similar to the search."""retriever_tool = create_retriever_tool(    retriever,    name="search_proper_nouns",    description=description,)
```

```
system = """You are an agent designed to interact with a SQL database.Given an input question, create a syntactically correct {dialect} query to run, then look at the results of the query and return the answer.Unless the user specifies a specific number of examples they wish to obtain, always limit your query to at most {top_k} results.You can order the results by a relevant column to return the most interesting examples in the database.Never query for all the columns from a specific table, only ask for the relevant columns given the question.You have access to tools for interacting with the database.Only use the given tools. Only use the information returned by the tools to construct your final answer.You MUST double check your query before executing it. If you get an error while executing a query, rewrite the query and try again.DO NOT make any DML statements (INSERT, UPDATE, DELETE, DROP etc.) to the database.If you need to filter on a proper noun, you must ALWAYS first look up the filter value using the "search_proper_nouns" tool! You have access to the following tables: {table_names}If the question does not seem related to the database, just return "I don't know" as the answer."""prompt = ChatPromptTemplate.from_messages(    [("system", system), ("human", "{input}"), MessagesPlaceholder("agent_scratchpad")])agent = create_sql_agent(    llm=llm,    db=db,    extra_tools=[retriever_tool],    prompt=prompt,    agent_type="openai-tools",    verbose=True,)
```

```
agent.invoke({"input": "How many albums does alis in chain have?"})
```

```
> Entering new AgentExecutor chain...Invoking: `search_proper_nouns` with `{'query': 'alis in chain'}`Alice In ChainsAisha DuoXisDa Lama Ao CaosA-SidesInvoking: `sql_db_query` with `SELECT COUNT(*) FROM Album WHERE ArtistId = (SELECT ArtistId FROM Artist WHERE Name = 'Alice In Chains')`[(1,)]Alice In Chains has 1 album.> Finished chain.
```

```
{'input': 'How many albums does alis in chain have?', 'output': 'Alice In Chains has 1 album.'}
```

As we can see, the agent used the `search_proper_nouns` tool in order to check how to correctly query the database for this specific artist.

## Next steps[​](#next-steps "Direct link to Next steps")

Under the hood, `create_sql_agent` is just passing in SQL tools to more generic agent constructors. To learn more about the built-in generic agent types as well as how to build custom agents, head to the [Agents Modules](https://python.langchain.com/docs/modules/agents/).

The built-in `AgentExecutor` runs a simple Agent action -\> Tool call -\> Agent action… loop. To build more complex agent runtimes, head to the [LangGraph section](https://python.langchain.com/docs/langgraph/).