diff --git a/tutorials/tracing/langgraph_agent_tracing_tutorial.ipynb b/tutorials/tracing/langgraph_agent_tracing_tutorial.ipynb
new file mode 100644
index 0000000000..f40c391475
--- /dev/null
+++ b/tutorials/tracing/langgraph_agent_tracing_tutorial.ipynb
@@ -0,0 +1,656 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "9f853e403eabd4f8",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "\n",
+ " \n",
+ " ![\"phoenix](\"https://storage.googleapis.com/arize-phoenix-assets/assets/phoenix-logo-light.svg\")
\n",
+ "
\n",
+ " Docs\n",
+ " |\n",
+ " GitHub\n",
+ " |\n",
+ " Community\n",
+ "
\n",
+ "\n",
+ "Tracing a LangGraph Agent
\n",
+ "\n",
+ "LangGraph provides tools to easily define a structured AI Agent. However, it can be challenging to understand what is going on under the hood and to pinpoint the cause of issues. Phoenix makes your LLM applications *observable* by visualizing the underlying structure of each call to your query engine and surfacing problematic \"spans\" of execution based on latency, token count, or other evaluation metrics.\n",
+ "\n",
+ "In this tutorial, you will:\n",
+ "- Build a simple SQL database agent using LangGraph,\n",
+ "- Record trace data in OpenInference format,\n",
+ "- Inspect the traces and spans of your application to identify sources of latency and cost\n",
+ "\n",
+ "ℹ️ This notebook requires an OpenAI API key."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b5a87813ffe7e4d2",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Setup\n",
+ "\n",
+ "First let's install our required packages and set our API keys"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "4a4be247",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "%pip install -U langgraph langchain_openai langchain_community arize-phoenix openinference-instrumentation-langchain"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "6c05a600f1afb5b6",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import getpass\n",
+ "import os\n",
+ "\n",
+ "\n",
+ "def _set_env(key: str):\n",
+ " if key not in os.environ:\n",
+ " os.environ[key] = getpass.getpass(f\"{key}:\")\n",
+ "\n",
+ "\n",
+ "_set_env(\"OPENAI_API_KEY\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "877d8c85825089d8",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Configure the database\n",
+ "\n",
+ "We will be creating a SQLite database for this tutorial. SQLite is a lightweight database that is easy to set up and use. We will be loading the `chinook` database, which is a sample database that represents a digital media store.\n",
+ "Find more information about the database [here](https://www.sqlitetutorial.net/sqlite-sample-database/).\n",
+ "\n",
+ "For convenience, we have hosted the database (`Chinook.db`) on a public GCS bucket."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "64b0bf1b14c2e902",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import requests\n",
+ "\n",
+ "url = \"https://storage.googleapis.com/benchmarks-artifacts/chinook/Chinook.db\"\n",
+ "\n",
+ "response = requests.get(url)\n",
+ "\n",
+ "if response.status_code == 200:\n",
+ " # Open a local file in binary write mode\n",
+ " with open(\"Chinook.db\", \"wb\") as file:\n",
+ " # Write the content of the response (the file) to the local file\n",
+ " file.write(response.content)\n",
+ " print(\"File downloaded and saved as Chinook.db\")\n",
+ "else:\n",
+ " print(f\"Failed to download the file. Status code: {response.status_code}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "61c8304aa5ceb6a5",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "We will use a handy SQL database wrapper available in the `langchain_community` package to interact with the database. The wrapper provides a simple interface to execute SQL queries and fetch results. We will also use the `langchain_openai` package to interact with the OpenAI API for language models later in the tutorial."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "1f1e1f4f86ed54",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from langchain_community.utilities import SQLDatabase\n",
+ "\n",
+ "db = SQLDatabase.from_uri(\"sqlite:///Chinook.db\")\n",
+ "print(db.dialect)\n",
+ "print(db.get_usable_table_names())\n",
+ "db.run(\"SELECT * FROM Artist LIMIT 10;\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "6959e93141d8099c",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Utility functions\n",
+ "\n",
+ "We will define a few utility functions to help us with the agent implementation. Specifically, we will wrap a `ToolNode` with a fallback to handle errors and surface them to the agent."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "deae8460e4cf72b1",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from typing import Any\n",
+ "\n",
+ "from langchain_core.messages import ToolMessage\n",
+ "from langchain_core.runnables import RunnableLambda, RunnableWithFallbacks\n",
+ "from langgraph.prebuilt import ToolNode\n",
+ "\n",
+ "\n",
+ "def create_tool_node_with_fallback(tools: list) -> RunnableWithFallbacks[Any, dict]:\n",
+ " \"\"\"\n",
+ " Create a ToolNode with a fallback to handle errors and surface them to the agent.\n",
+ " \"\"\"\n",
+ " return ToolNode(tools).with_fallbacks(\n",
+ " [RunnableLambda(handle_tool_error)], exception_key=\"error\"\n",
+ " )\n",
+ "\n",
+ "\n",
+ "def handle_tool_error(state) -> dict:\n",
+ " error = state.get(\"error\")\n",
+ " tool_calls = state[\"messages\"][-1].tool_calls\n",
+ " return {\n",
+ " \"messages\": [\n",
+ " ToolMessage(\n",
+ " content=f\"Error: {repr(error)}\\n please fix your mistakes.\",\n",
+ " tool_call_id=tc[\"id\"],\n",
+ " )\n",
+ " for tc in tool_calls\n",
+ " ]\n",
+ " }"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d0196604f8cbb07b",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Define tools for the agent\n",
+ "\n",
+ "We will define a few tools that the agent will use to interact with the database.\n",
+ "\n",
+ "1. `list_tables_tool`: Fetch the available tables from the database\n",
+ "2. `get_schema_tool`: Fetch the DDL for a table\n",
+ "3. `db_query_tool`: Execute the query and fetch the results OR return an error message if the query fails\n",
+ "\n",
+ "For the first two tools, we will grab them from the `SQLDatabaseToolkit`, also available in the `langchain_community` package."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "452d049a3d2a4406",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from langchain_community.agent_toolkits import SQLDatabaseToolkit\n",
+ "from langchain_openai import ChatOpenAI\n",
+ "\n",
+ "toolkit = SQLDatabaseToolkit(db=db, llm=ChatOpenAI(model=\"gpt-4o\"))\n",
+ "tools = toolkit.get_tools()\n",
+ "\n",
+ "list_tables_tool = next(tool for tool in tools if tool.name == \"sql_db_list_tables\")\n",
+ "get_schema_tool = next(tool for tool in tools if tool.name == \"sql_db_schema\")\n",
+ "\n",
+ "print(list_tables_tool.invoke(\"\"))\n",
+ "\n",
+ "print(get_schema_tool.invoke(\"Artist\"))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "c16359edada327fa",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "The third will be defined manually. For the `db_query_tool`, we will execute the query against the database and return the results."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "f7eb708ecb4c7cfc",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from langchain_core.tools import tool\n",
+ "\n",
+ "\n",
+ "@tool\n",
+ "def db_query_tool(query: str) -> str:\n",
+ " \"\"\"\n",
+ " Execute a SQL query against the database and get back the result.\n",
+ " If the query is not correct, an error message will be returned.\n",
+ " If an error is returned, rewrite the query, check the query, and try again.\n",
+ " \"\"\"\n",
+ " result = db.run_no_throw(query)\n",
+ " if not result:\n",
+ " return \"Error: Query failed. Please rewrite your query and try again.\"\n",
+ " return result\n",
+ "\n",
+ "\n",
+ "print(db_query_tool.invoke(\"SELECT * FROM Artist LIMIT 10;\"))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "f1d66db8b8621639",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "While not strictly a tool, we will prompt an LLM to check for common mistakes in the query and later add this as a node in the workflow."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "293017e8f05ac2b3",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from langchain_core.prompts import ChatPromptTemplate\n",
+ "\n",
+ "query_check_system = \"\"\"You are a SQL expert with a strong attention to detail.\n",
+ "Double check the SQLite query for common mistakes, including:\n",
+ "- Using NOT IN with NULL values\n",
+ "- Using UNION when UNION ALL should have been used\n",
+ "- Using BETWEEN for exclusive ranges\n",
+ "- Data type mismatch in predicates\n",
+ "- Properly quoting identifiers\n",
+ "- Using the correct number of arguments for functions\n",
+ "- Casting to the correct data type\n",
+ "- Using the proper columns for joins\n",
+ "\n",
+ "If there are any of the above mistakes, rewrite the query. If there are no mistakes, just reproduce the original query.\n",
+ "\n",
+ "You will call the appropriate tool to execute the query after running this check.\"\"\"\n",
+ "\n",
+ "query_check_prompt = ChatPromptTemplate.from_messages(\n",
+ " [(\"system\", query_check_system), (\"placeholder\", \"{messages}\")]\n",
+ ")\n",
+ "query_check = query_check_prompt | ChatOpenAI(model=\"gpt-4o\", temperature=0).bind_tools(\n",
+ " [db_query_tool], tool_choice=\"required\"\n",
+ ")\n",
+ "\n",
+ "query_check.invoke({\"messages\": [(\"user\", \"SELECT * FROM Artist LIMIT 10;\")]})"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "66f88452151e8188",
+ "metadata": {
+ "collapsed": false,
+ "jupyter": {
+ "outputs_hidden": false
+ }
+ },
+ "source": [
+ "## Define the workflow\n",
+ "\n",
+ "We will then define the workflow for the agent. The agent will first force-call the `list_tables_tool` to fetch the available tables from the database, then follow the steps mentioned at the beginning of the tutorial."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "2fd9e41c-95c3-47aa-9a12-80b78cc7ac2d",
+ "metadata": {},
+ "source": [
+ "\n",
+ "
Using Pydantic with LangChain
\n",
+ "
\n",
+ " This notebook uses Pydantic v2 BaseModel, which requires langchain-core >= 0.3. Using langchain-core < 0.3 will result in errors due to mixing of Pydantic v1 and v2 BaseModels.\n",
+ "
\n",
+ "