Asking Questions of a DataFrame: How LangChain's Pandas Agent Builds Charts

Exploring a dataset used to require fluency in a query language or a plotting library before you could see a single trend. With an LLM-driven agent in front of a pandas DataFrame, you can instead type a request such as "plot the gender count with bars" and get back both a chart and a short explanation. That convenience comes with real risk, because the agent works by writing and executing Python on your machine. This guide explains the three components involved, follows a question step by step until it becomes a chart, shows how to inspect the code the agent writes, and lists the safeguards you need before trusting its output.

One point up front: create_pandas_dataframe_agent ships in LangChain's experimental package. It is well suited to prototyping and exploration, but it is not intended for production use unless you add thorough human review and isolation around it.

From syntax to intent

The traditional workflow asks you to know how to do something before you can learn anything: which pandas method groups rows, which matplotlib call draws a bar chart, how to label the axes. The agent approach inverts that. You describe what you want to know, and the model works out how to compute and display it.

The practical effect is that more people can work with data directly. A business analyst or domain expert who understands the questions but not the syntax can reach an answer without waiting for someone who knows the libraries. The attention shifts from how to write the code to which questions actually matter for a decision. The trade-off, covered below, is that you now have to verify code you did not write.

The three components behind the agent

A useful way to picture the system is as a reasoning engine, a structured data store and a connector between them.

The LLM as the reasoning engine

The language model interprets your request, writes the Python needed to answer it and chooses a suitable chart type, for instance a bar chart for counts per category. Its job is to bridge natural language and executable logic, including working out what the data actually represents.

The DataFrame as the organized data store

pandas holds the data as a table of rows and labeled columns. Take the UCI Student Alcohol Consumption dataset as an example: attributes such as sex and age are stored as columns, ready to be filtered and aggregated. This consistent structure is what lets the agent run precise operations quickly.

LangChain as the connector

create_pandas_dataframe_agent provides the prebuilt prompt and tooling that let the model reach into the DataFrame. Under the hood, the agent receives a Python execution tool with your DataFrame available as df, and a prompt that tells the model to use it. You do not have to wire up that connection yourself.

How a question becomes a chart

Following a single request through the system makes each component's role clear. Suppose the question is "Plot the gender count with bars."

1. The question arrives. The model receives the text and starts interpreting what is being asked.
2. The model maps the request to the data. It recognizes that "gender" corresponds to the sex column and decides that a bar chart fits a count by category.
3. The data is accessed. There is no separate database; the DataFrame in memory is the data source.
4. The analysis runs. The model writes code that counts the M and F values, applying any filtering required, and the connector executes it.
5. The result is interpreted. The model reads the counts and frames them in the context of the student population.
6. The answer is presented. You get a bar chart of the distribution together with a plain-language summary.

Steps 2 and 4 are where most mistakes happen. A wrong column mapping or a subtly incorrect filter will still produce a clean-looking chart, which is exactly why the next section matters.

Looking inside: intermediate steps and generated code

It helps to separate the code you run from the code the agent runs. You might call df.head() yourself to look at the first five rows and understand the columns. The agent, by contrast, writes its own code to answer each request, and you can make that code visible.

When creating the agent with create_pandas_dataframe_agent, pass return_intermediate_steps=True. The result then includes each action the agent took, along with the code it ran and the output it observed. This supports three things:

• Verification: you can confirm the agent computed its answer rather than guessing. You will see real expressions such as len(df) to count rows or df[df['age'] == 18] to select 18-year-old students.
• Debugging: setting verbose=True additionally prints the agent's reasoning and generated code to the console as it runs, so when a result looks odd you can see where the logic went wrong.
• Learning: the agent stops being a black box and becomes a live demonstration of how pandas is used to manipulate data.

The two options are complementary. verbose=True is convenient while you watch a run interactively, whereas return_intermediate_steps=True hands the steps back as data, which you can log, display in a notebook or check automatically.

Safety: the agent executes the code it writes

Because the agent runs model-generated Python, a malicious or merely mistaken instruction can read files, make network calls or delete data with the same privileges as your process. Recent versions of langchain_experimental make this explicit by refusing to build the agent unless you pass allow_dangerous_code=True; check the current documentation for your version. That flag is an acknowledgement of the risk, not a mitigation.

Treat any data you did not create as untrusted too. A cell containing text such as an instruction to the model can influence the code it writes, a form of prompt injection that is easy to overlook when the input is a spreadsheet.

A checklist for responsible use

Keep a person in the loop on every project and work through these points:

• Run the agent in a sandbox, such as a container or a disposable environment with no credentials and limited file and network access, so that unintended or malicious code cannot cause harm.
• Write clear, specific prompts. Naming the exact columns and the aggregation you want reduces the chance that the agent picks the wrong field or invents one.
• Check results against your own knowledge. Never accept a chart at face value; use the intermediate steps to confirm the correct columns, filters and calculations were used.
• Iterate. Analysis is a dialogue. If the first chart is not quite right, use what the intermediate steps reveal to sharpen the next request.
• Work on a copy of the data. Operations that modify the DataFrame in place can silently change what later questions see.

Key takeaways

• A pandas agent combines three parts: an LLM that reasons and writes code, a DataFrame that holds structured data and LangChain's create_pandas_dataframe_agent that connects them.
• Most errors occur when the model maps words to columns or writes the analysis code, and they can still produce convincing charts.
• return_intermediate_steps=True and verbose=True expose the generated code, making verification and debugging possible.
• The agent executes arbitrary Python, lives in an experimental package and needs sandboxing and human review before it goes anywhere near production.
• The agent supplies speed; you supply the domain context and critical judgement that turn its output into an accurate conclusion.