Agex 101¶

In this demo, we'll start with a 'wide' dataset of stock prices and use an agex agent to perform a classic data science task: reshaping it into a 'long' format and then visualizing the result.

In [1]:

import plotly.express as px

df = px.data.stocks()
display(df.head())

import plotly.express as px df = px.data.stocks() display(df.head())

	date	GOOG	AAPL	AMZN	FB	NFLX	MSFT
0	2018-01-01	1.000000	1.000000	1.000000	1.000000	1.000000	1.000000
1	2018-01-08	1.018172	1.011943	1.061881	0.959968	1.053526	1.015988
2	2018-01-15	1.032008	1.019771	1.053240	0.970243	1.049860	1.020524
3	2018-01-22	1.066783	0.980057	1.140676	1.016858	1.307681	1.066561
4	2018-01-29	1.008773	0.917143	1.163374	1.018357	1.273537	1.040708

First, we create an Agent. Instead of tools, we give our agent direct access to the pandas and plotly libraries, creating a guided sandbox environment for it to work in. Since these are popular libraries, the agent will already be familiar with them. By choosing visibility="low" we skip including docstrings and fn signatures in the agent context, but we will let the agent know these modules are available.

In [2]:

import pandas as pd
import plotly.graph_objects as go
from agex import Agent

agent = Agent(name="data_expert")

# Register pandas & plotly for the agent
agent.cls(go.Figure, visibility="low")
agent.module(px, visibility="low")
agent.module(pd, visibility="low")

import pandas as pd import plotly.graph_objects as go from agex import Agent agent = Agent(name="data_expert") # Register pandas & plotly for the agent agent.cls(go.Figure, visibility="low") agent.module(px, visibility="low") agent.module(pd, visibility="low")

Next, we define the agent's skills using the @agent.task decorator. We provide a function signature with type hints, and the agent writes the implementation at runtime. The types are the contract.

In [3]:

@agent.task
def transform_data(prompt: str, df: pd.DataFrame) -> pd.DataFrame:  # type: ignore[return-value]
    """Transform the data according to the prompt."""
    pass


@agent.task
def plot_data(prompt: str, df: pd.DataFrame) -> go.Figure:  # type: ignore[return-value]
    """Plot the data according to the prompt."""
    pass

@agent.task def transform_data(prompt: str, df: pd.DataFrame) -> pd.DataFrame: # type: ignore[return-value] """Transform the data according to the prompt.""" pass @agent.task def plot_data(prompt: str, df: pd.DataFrame) -> go.Figure: # type: ignore[return-value] """Plot the data according to the prompt.""" pass

Let's ask the agent to transform our data. Notice that the agent will return a real, live DataFrame directly to us (not JSON).

In [5]:

prompt = "Reshape this data from wide to long with 'date', 'company', and 'price' cols"
long_df = transform_data(prompt, df)
display(long_df.head())

prompt = "Reshape this data from wide to long with 'date', 'company', and 'price' cols" long_df = transform_data(prompt, df) display(long_df.head())

	date	company	price
0	2018-01-01	GOOG	1.000000
1	2018-01-08	GOOG	1.018172
2	2018-01-15	GOOG	1.032008
3	2018-01-22	GOOG	1.066783
4	2018-01-29	GOOG	1.008773

That's a real DataFrame, but how did the agent create it? We can see the agent's "thinking" by re-running the task with an on_event handler.

In [4]:

from agex import ActionEvent, Event, TaskStartEvent


def display_action(event: Event):
    if isinstance(event, ActionEvent):
        display(event)


prompt = "Reshape this data from wide to long with 'date', 'company', and 'price' cols"
long_df = transform_data(prompt, df, on_event=display_action)

from agex import ActionEvent, Event, TaskStartEvent def display_action(event: Event): if isinstance(event, ActionEvent): display(event) prompt = "Reshape this data from wide to long with 'date', 'company', and 'price' cols" long_df = transform_data(prompt, df, on_event=display_action)

🧠 ActionEvent - data_expert

2025-07-31T13:47:15Z

💭 Thinking:

The task is to reshape the given wide DataFrame into a long format with specific columns: 'date', 'company', and 'price'. Currently, the DataFrame has a 'date' column and multiple columns for each company's stock prices. To achieve the long format, I will use pandas' melt function, specifying 'date' as the id_vars, and the remaining columns as value_vars. The var_name will be 'company' and the value_name will be 'price'. After melting, the DataFrame will have the desired structure. I will verify the operation by inspecting the resulting DataFrame, then call `task_success()` with the result.

🐍 Code:

import pandas as pd

# Access the input DataFrame
df = inputs.df

# Reshape from wide to long format using melt
result = df.melt(id_vars=['date'], var_name='company', value_name='price')

# Complete the task by returning the transformed DataFrame
task_success(result)

Now that the agent has prepared the data, let's ask it to create the final visualization.

In [8]:

prompt = "Create a line chart of the stock prices over time, using a different color for each company."
plot = plot_data(prompt, long_df, on_event=display_action)
display(plot)

prompt = "Create a line chart of the stock prices over time, using a different color for each company." plot = plot_data(prompt, long_df, on_event=display_action) display(plot)

🧠 ActionEvent - data_expert

2025-07-31T13:48:30Z

💭 Thinking:

The task is to create a line chart of stock prices over time, with different colors for each company. The data is stored in a pandas DataFrame 'df' with columns 'date', 'company', and 'price'. The prompt indicates a time series plot that distinguishes companies by color. I will use plotly.express for an interactive and clear plot. First, I need to ensure I import plotly.express. Then, I will generate the line plot with 'date' on the x-axis, 'price' on the y-axis, and 'company' as the color dimension. After creating the figure, I will use view_image to display it, then verify the output with task_continue, and finally call task_success with the figure object.

🐍 Code:

import plotly.express as px

# Create the line chart with different colors for each company
fig = px.line(inputs.df, x='date', y='price', color='company', title='Stock Prices Over Time')

# View the figure to see the plot
view_image(fig)

# Proceed to verification
task_continue("Created line chart of stock prices over time with company distinction", fig)

# When verified, complete the task
# task_success(fig)  # Uncomment this line after verification to complete the task.

🧠 ActionEvent - data_expert

2025-07-31T13:48:33Z

💭 Thinking:

The plot appears to be correctly generated, with multiple lines representing stock prices over time for different companies. The colors differentiate each company, as intended. To finalize, I will now call task_success with the figure object to indicate successful completion of the task.

🐍 Code:

task_success(fig)  # Confirmed the plot is correct, now complete the task.

Notice the view_image in the first action. That call put the image in the agent's equivalent of stdout. So the agent took a look at its own plot before returning it as a task_success.

In this demo, we sampled how agex agents':

• Use Python libraries directly.
• Receive and return complex objects like DataFrames and Figures.
• Work through tasks iteratively in a REPL-esque environement.
• Provide observability into the agent thought process.

What's Next?

Check out:

• routing.ipynb to see agex integration with OSMnx and Folium for interactive route planning.
• vision.ipynb to see vision capable models paired with Pillow.