Deep Research with LangGraph: Build an AI Research Assistant from Scratch

To create the assistant we are going to use the following architecture:

	

		
!uv init deepresearcher
	
	

		
			
		
	
	
Copied

	

		
Initialized project `deepresearcher` at `/Users/macm1/Documents/web/portafolio/posts/notebooks_translated/deepresearcher`
	

	

		
!cd deepresearcher && uv sync
	
	

		
			
		
	
	
Copied

	

		
Using CPython 3.12.8
Creating virtual environment at: .venv
Resolved 1 package in 24ms
Audited in 0.04ms
	

	

		
!cd deepresearcher && source .venv/bin/activate
	
	

		
			
		
	
	
Copied

	

		
!cd deepresearcher && source .venv/bin/activate && uv add "alive-progress>=3.3.0" "dotenv>=0.9.9" "grandalf>=0.8" "ipykernel>=6.30.1" "langchain>=0.3.27" "langchain-anthropic>=0.3.21" "langchain-community>=0.3.29" "langchain-mcp-adapters>=0.1.11" "langchain-openai>=0.3.33" "langgraph>=0.6.7" "rich>=14.1.0" "tavily-python>=0.7.12"
	
	

		
			
		
	
	
Copied

	

		
Resolved 120 packages in 474ms
⠙ Preparing packages... (0/22)
⠙ Preparing packages... (0/22)-------------     0 B/72.30 KiB
⠙ Preparing packages... (0/22)------------- 16.00 KiB/72.30 KiB
⠙ Preparing packages... (0/22)------------- 32.00 KiB/72.30 KiB
⠙ Preparing packages... (0/22)[2m---------- 48.00 KiB/72.30 KiB
⠙ Preparing packages... (0/22)[2m---------- 48.00 KiB/72.30 KiB
starlette            ------------------------------ 48.00 KiB/72.30 KiB
⠙ Preparing packages... (0/22)-------------     0 B/452.54 KiB
starlette            ------------------------------ 64.00 KiB/72.30 KiB
⠙ Preparing packages... (0/22)-------------     0 B/452.54 KiB
starlette            ------------------------------ 64.00 KiB/72.30 KiB
⠙ Preparing packages... (0/22)------------- 16.00 KiB/452.54 KiB
starlette            ------------------------------ 72.30 KiB/72.30 KiB
⠙ Preparing packages... (0/22)------------- 16.00 KiB/452.54 KiB
starlette            ------------------------------ 72.30 KiB/72.30 KiB
⠙ Preparing packages... (0/22)------------- 32.00 KiB/452.54 KiB
⠙ Preparing packages... (0/22)------------- 32.00 KiB/452.54 KiB
⠙ Preparing packages... (0/22)------------- 48.00 KiB/452.54 KiB
⠙ Preparing packages... (0/22)------------- 48.00 KiB/452.54 KiB
regex                ------------------------------     0 B/282.15 KiB
⠙ Preparing packages... (0/22)------------- 48.00 KiB/452.54 KiB
regex                ------------------------------     0 B/282.15 KiB
⠙ Preparing packages... (0/22)------------- 48.00 KiB/452.54 KiB
regex                ------------------------------     0 B/282.15 KiB
⠙ Preparing packages... (0/22)------------- 48.00 KiB/452.54 KiB
regex                ------------------------------     0 B/282.15 KiB
pydantic             ------------------------------ 48.00 KiB/452.54 KiB
⠙ Preparing packages... (0/22)-------------     0 B/6.89 MiB
regex                ------------------------------     0 B/282.15 KiB
pydantic             ------------------------------ 63.88 KiB/452.54 KiB
⠙ Preparing packages... (0/22)-------------     0 B/6.89 MiB
regex                ------------------------------     0 B/282.15 KiB
pydantic             ------------------------------ 79.88 KiB/452.54 KiB
⠙ Preparing packages... (0/22)-------------     0 B/6.89 MiB
langchain-openai     ------------------------------     0 B/80.01 KiB
langgraph            ------------------------------ 14.88 KiB/153.08 KiB
regex                ------------------------------ 16.00 KiB/282.15 KiB
anthropic            ------------------------------ 14.01 KiB/349.09 KiB
ormsgpack            ------------------------------     0 B/360.88 KiB
langsmith            ------------------------------     0 B/389.92 KiB
pydantic             ------------------------------ 127.88 KiB/452.54 KiB
langchain-core       ------------------------------     0 B/458.91 KiB
aiohttp              ------------------------------ 14.91 KiB/480.28 KiB
pydantic-core        ------------------------------     0 B/1.81 MiB
⠙ Preparing packages... (0/22)------------ 16.00 KiB/6.89 MiB
langchain-mcp-adapters ------------------------------ 14.87 KiB/19.95 KiB
langgraph-prebuilt     ------------------------------ 17.00 KiB/33.48 KiB
langgraph-checkpoint   ------------------------------ 30.38 KiB/45.17 KiB
langchain-anthropic    ------------------------------ 16.00 KiB/45.33 KiB
langchain-openai       ------------------------------ 48.00 KiB/80.01 KiB
langchain              ------------------------------ 46.88 KiB/91.55 KiB
langgraph              ------------------------------ 46.88 KiB/153.08 KiB
mcp                    ------------------------------ 22.84 KiB/169.60 KiB
psutil                 ------------------------------ 14.91 KiB/233.57 KiB
regex                  ------------------------------ 48.97 KiB/282.15 KiB
anthropic              ------------------------------ 46.01 KiB/349.09 KiB
ormsgpack              ------------------------------ 16.00 KiB/360.88 KiB
langsmith              ------------------------------ 48.00 KiB/389.92 KiB
pydantic               ------------------------------ 191.88 KiB/452.54 KiB
langchain-core         ------------------------------ 32.00 KiB/458.91 KiB
aiohttp                ------------------------------ 62.91 KiB/480.28 KiB
ipython                ------------------------------ 46.88 KiB/604.41 KiB
openai                 ------------------------------ 14.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 48.00 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 62.03 KiB/6.89 MiB
langgraph-prebuilt     ------------------------------ 33.00 KiB/33.48 KiB
langgraph-checkpoint   ------------------------------ 30.38 KiB/45.17 KiB
langchain-anthropic    ------------------------------ 32.00 KiB/45.33 KiB
langchain-openai       ------------------------------ 58.80 KiB/80.01 KiB
langchain              ------------------------------ 46.88 KiB/91.55 KiB
langgraph              ------------------------------ 62.88 KiB/153.08 KiB
mcp                    ------------------------------ 24.77 KiB/169.60 KiB
psutil                 ------------------------------ 30.91 KiB/233.57 KiB
regex                  ------------------------------ 64.97 KiB/282.15 KiB
anthropic              ------------------------------ 62.01 KiB/349.09 KiB
ormsgpack              ------------------------------ 32.00 KiB/360.88 KiB
langsmith              ------------------------------ 64.00 KiB/389.92 KiB
pydantic               ------------------------------ 207.88 KiB/452.54 KiB
langchain-core         ------------------------------ 32.00 KiB/458.91 KiB
aiohttp                ------------------------------ 63.29 KiB/480.28 KiB
ipython                ------------------------------ 61.67 KiB/604.41 KiB
openai                 ------------------------------ 30.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 64.00 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 78.03 KiB/6.89 MiB
langgraph-checkpoint   ------------------------------ 45.17 KiB/45.17 KiB
langchain-anthropic    ------------------------------ 45.33 KiB/45.33 KiB
langchain-openai       ------------------------------ 80.00 KiB/80.01 KiB
langchain              ------------------------------ 62.88 KiB/91.55 KiB
langgraph              ------------------------------ 78.88 KiB/153.08 KiB
mcp                    ------------------------------ 40.77 KiB/169.60 KiB
psutil                 ------------------------------ 78.91 KiB/233.57 KiB
regex                  ------------------------------ 112.00 KiB/282.15 KiB
anthropic              ------------------------------ 62.01 KiB/349.09 KiB
ormsgpack              ------------------------------ 78.35 KiB/360.88 KiB
langsmith              ------------------------------ 93.36 KiB/389.92 KiB
pydantic               ------------------------------ 243.15 KiB/452.54 KiB
langchain-core         ------------------------------ 32.00 KiB/458.91 KiB
aiohttp                ------------------------------ 79.29 KiB/480.28 KiB
ipython                ------------------------------ 77.67 KiB/604.41 KiB
openai                 ------------------------------ 30.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 96.00 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 78.03 KiB/6.89 MiB
langchain-anthropic    ------------------------------ 45.33 KiB/45.33 KiB
langchain-openai       ------------------------------ 80.00 KiB/80.01 KiB
langchain              ------------------------------ 91.55 KiB/91.55 KiB
langgraph              ------------------------------ 78.88 KiB/153.08 KiB
mcp                    ------------------------------ 56.77 KiB/169.60 KiB
psutil                 ------------------------------ 110.91 KiB/233.57 KiB
regex                  ------------------------------ 144.00 KiB/282.15 KiB
anthropic              ------------------------------ 62.01 KiB/349.09 KiB
ormsgpack              ------------------------------ 160.73 KiB/360.88 KiB
langsmith              ------------------------------ 128.00 KiB/389.92 KiB
pydantic               ------------------------------ 243.15 KiB/452.54 KiB
langchain-core         ------------------------------ 61.10 KiB/458.91 KiB
aiohttp                ------------------------------ 95.29 KiB/480.28 KiB
ipython                ------------------------------ 109.67 KiB/604.41 KiB
openai                 ------------------------------ 46.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 129.86 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 78.03 KiB/6.89 MiB
langchain-openai       ------------------------------ 80.00 KiB/80.01 KiB
langchain              ------------------------------ 91.55 KiB/91.55 KiB
langgraph              ------------------------------ 94.88 KiB/153.08 KiB
mcp                    ------------------------------ 56.77 KiB/169.60 KiB
psutil                 ------------------------------ 126.91 KiB/233.57 KiB
regex                  ------------------------------ 207.89 KiB/282.15 KiB
anthropic              ------------------------------ 62.01 KiB/349.09 KiB
ormsgpack              ------------------------------ 190.35 KiB/360.88 KiB
langsmith              ------------------------------ 144.00 KiB/389.92 KiB
pydantic               ------------------------------ 271.88 KiB/452.54 KiB
langchain-core         ------------------------------ 61.10 KiB/458.91 KiB
aiohttp                ------------------------------ 127.29 KiB/480.28 KiB
ipython                ------------------------------ 109.67 KiB/604.41 KiB
openai                 ------------------------------ 62.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 192.00 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 78.03 KiB/6.89 MiB
langchain-openai       ------------------------------ 80.00 KiB/80.01 KiB
langchain              ------------------------------ 91.55 KiB/91.55 KiB
langgraph              ------------------------------ 94.88 KiB/153.08 KiB
mcp                    ------------------------------ 56.77 KiB/169.60 KiB
psutil                 ------------------------------ 142.91 KiB/233.57 KiB
regex                  ------------------------------ 224.00 KiB/282.15 KiB
anthropic              ------------------------------ 78.01 KiB/349.09 KiB
ormsgpack              ------------------------------ 190.35 KiB/360.88 KiB
langsmith              ------------------------------ 144.00 KiB/389.92 KiB
pydantic               ------------------------------ 271.88 KiB/452.54 KiB
langchain-core         ------------------------------ 61.10 KiB/458.91 KiB
aiohttp                ------------------------------ 127.29 KiB/480.28 KiB
ipython                ------------------------------ 125.67 KiB/604.41 KiB
openai                 ------------------------------ 62.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 208.00 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 78.03 KiB/6.89 MiB
langchain              ------------------------------ 91.55 KiB/91.55 KiB
langgraph              ------------------------------ 110.88 KiB/153.08 KiB
mcp                    ------------------------------ 56.77 KiB/169.60 KiB
psutil                 ------------------------------ 158.91 KiB/233.57 KiB
regex                  ------------------------------ 256.00 KiB/282.15 KiB
anthropic              ------------------------------ 78.01 KiB/349.09 KiB
ormsgpack              ------------------------------ 236.32 KiB/360.88 KiB
langsmith              ------------------------------ 144.00 KiB/389.92 KiB
pydantic               ------------------------------ 287.88 KiB/452.54 KiB
langchain-core         ------------------------------ 61.10 KiB/458.91 KiB
aiohttp                ------------------------------ 143.29 KiB/480.28 KiB
ipython                ------------------------------ 141.67 KiB/604.41 KiB
openai                 ------------------------------ 62.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 240.00 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 78.03 KiB/6.89 MiB
langchain              ------------------------------ 91.55 KiB/91.55 KiB
langgraph              ------------------------------ 110.88 KiB/153.08 KiB
mcp                    ------------------------------ 56.77 KiB/169.60 KiB
psutil                 ------------------------------ 174.91 KiB/233.57 KiB
anthropic              ------------------------------ 78.01 KiB/349.09 KiB
ormsgpack              ------------------------------ 270.35 KiB/360.88 KiB
langsmith              ------------------------------ 144.00 KiB/389.92 KiB
pydantic               ------------------------------ 287.88 KiB/452.54 KiB
langchain-core         ------------------------------ 77.10 KiB/458.91 KiB
aiohttp                ------------------------------ 143.29 KiB/480.28 KiB
ipython                ------------------------------ 141.67 KiB/604.41 KiB
openai                 ------------------------------ 62.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 304.00 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 78.03 KiB/6.89 MiB
langgraph              ------------------------------ 110.88 KiB/153.08 KiB
mcp                    ------------------------------ 56.77 KiB/169.60 KiB
psutil                 ------------------------------ 190.91 KiB/233.57 KiB
anthropic              ------------------------------ 78.01 KiB/349.09 KiB
ormsgpack              ------------------------------ 270.35 KiB/360.88 KiB
langsmith              ------------------------------ 160.00 KiB/389.92 KiB
pydantic               ------------------------------ 287.88 KiB/452.54 KiB
langchain-core         ------------------------------ 77.10 KiB/458.91 KiB
aiohttp                ------------------------------ 143.29 KiB/480.28 KiB
ipython                ------------------------------ 205.67 KiB/604.41 KiB
openai                 ------------------------------ 62.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 304.00 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 78.03 KiB/6.89 MiB
langgraph              ------------------------------ 142.88 KiB/153.08 KiB
mcp                    ------------------------------ 72.77 KiB/169.60 KiB
psutil                 ------------------------------ 222.91 KiB/233.57 KiB
anthropic              ------------------------------ 78.01 KiB/349.09 KiB
langsmith              ------------------------------ 160.00 KiB/389.92 KiB
pydantic               ------------------------------ 303.88 KiB/452.54 KiB
langchain-core         ------------------------------ 77.10 KiB/458.91 KiB
aiohttp                ------------------------------ 175.18 KiB/480.28 KiB
ipython                ------------------------------ 230.51 KiB/604.41 KiB
openai                 ------------------------------ 62.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 624.00 KiB/1.81 MiB
⠙ Preparing packages... (0/22)-------------- 94.03 KiB/6.89 MiB
langgraph              ------------------------------ 142.88 KiB/153.08 KiB
mcp                    ------------------------------ 72.77 KiB/169.60 KiB
psutil                 ------------------------------ 233.57 KiB/233.57 KiB
anthropic              ------------------------------ 94.01 KiB/349.09 KiB
langsmith              ------------------------------ 176.00 KiB/389.92 KiB
pydantic               ------------------------------ 303.88 KiB/452.54 KiB
langchain-core         ------------------------------ 93.10 KiB/458.91 KiB
aiohttp                ------------------------------ 191.18 KiB/480.28 KiB
ipython                ------------------------------ 246.51 KiB/604.41 KiB
openai                 ------------------------------ 78.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 960.00 KiB/1.81 MiB
⠹ Preparing packages... (10/22)------------- 94.03 KiB/6.89 MiB
langgraph              ------------------------------ 153.08 KiB/153.08 KiB
mcp                    ------------------------------ 78.89 KiB/169.60 KiB
anthropic              ------------------------------ 94.01 KiB/349.09 KiB
langsmith              ------------------------------ 176.00 KiB/389.92 KiB
pydantic               ------------------------------ 319.88 KiB/452.54 KiB
langchain-core         ------------------------------ 93.10 KiB/458.91 KiB
aiohttp                ------------------------------ 191.18 KiB/480.28 KiB
ipython                ------------------------------ 253.67 KiB/604.41 KiB
openai                 ------------------------------ 78.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 1.00 MiB/1.81 MiB
⠹ Preparing packages... (10/22)------------- 94.03 KiB/6.89 MiB
mcp                    ------------------------------ 94.89 KiB/169.60 KiB
anthropic              ------------------------------ 94.01 KiB/349.09 KiB
langsmith              ------------------------------ 192.00 KiB/389.92 KiB
pydantic               ------------------------------ 319.88 KiB/452.54 KiB
langchain-core         ------------------------------ 109.10 KiB/458.91 KiB
aiohttp                ------------------------------ 207.29 KiB/480.28 KiB
ipython                ------------------------------ 269.67 KiB/604.41 KiB
openai                 ------------------------------ 78.88 KiB/985.14 KiB
pydantic-core          ------------------------------ 1.04 MiB/1.81 MiB
⠹ Preparing packages... (10/22)------------- 94.03 KiB/6.89 MiB
mcp                    ------------------------------ 110.89 KiB/169.60 KiB
anthropic              ------------------------------ 110.01 KiB/349.09 KiB
langsmith              ------------------------------ 352.00 KiB/389.92 KiB
pydantic               ------------------------------ 367.88 KiB/452.54 KiB
langchain-core         ------------------------------ 141.10 KiB/458.91 KiB
aiohttp                ------------------------------ 367.29 KiB/480.28 KiB
ipython                ------------------------------ 333.67 KiB/604.41 KiB
openai                 ------------------------------ 94.88 KiB/985.14 KiB
⠹ Preparing packages... (10/22)-------------- 126.03 KiB/6.89 MiB
mcp                    ------------------------------ 110.89 KiB/169.60 KiB
anthropic              ------------------------------ 110.01 KiB/349.09 KiB
langsmith              ------------------------------ 352.00 KiB/389.92 KiB
pydantic               ------------------------------ 367.88 KiB/452.54 KiB
langchain-core         ------------------------------ 157.10 KiB/458.91 KiB
aiohttp                ------------------------------ 367.29 KiB/480.28 KiB
ipython                ------------------------------ 333.67 KiB/604.41 KiB
openai                 ------------------------------ 94.88 KiB/985.14 KiB
⠹ Preparing packages... (10/22)-------------- 638.03 KiB/6.89 MiB
mcp                    ------------------------------ 126.89 KiB/169.60 KiB
anthropic              ------------------------------ 142.01 KiB/349.09 KiB
langsmith              ------------------------------ 382.70 KiB/389.92 KiB
langchain-core         ------------------------------ 205.10 KiB/458.91 KiB
aiohttp                ------------------------------ 480.28 KiB/480.28 KiB
ipython                ------------------------------ 380.72 KiB/604.41 KiB
openai                 ------------------------------ 110.88 KiB/985.14 KiB
⠹ Preparing packages... (10/22)-------------- 2.05 MiB/6.89 MiB
mcp                    ------------------------------ 126.89 KiB/169.60 KiB
anthropic              ------------------------------ 142.01 KiB/349.09 KiB
langchain-core         ------------------------------ 205.10 KiB/458.91 KiB
aiohttp                ------------------------------ 480.28 KiB/480.28 KiB
ipython                ------------------------------ 390.93 KiB/604.41 KiB
openai                 ------------------------------ 110.88 KiB/985.14 KiB
⠹ Preparing packages... (10/22)-------------- 2.22 MiB/6.89 MiB
mcp                    ------------------------------ 142.89 KiB/169.60 KiB
anthropic              ------------------------------ 158.01 KiB/349.09 KiB
langchain-core         ------------------------------ 221.10 KiB/458.91 KiB
ipython                ------------------------------ 406.93 KiB/604.41 KiB
openai                 ------------------------------ 126.66 KiB/985.14 KiB
⠹ Preparing packages... (10/22)-------------- 2.22 MiB/6.89 MiB
mcp                    ------------------------------ 142.89 KiB/169.60 KiB
anthropic              ------------------------------ 158.01 KiB/349.09 KiB
langchain-core         ------------------------------ 221.10 KiB/458.91 KiB
ipython                ------------------------------ 422.93 KiB/604.41 KiB
openai                 ------------------------------ 126.66 KiB/985.14 KiB
⠹ Preparing packages... (10/22)-------------- 2.28 MiB/6.89 MiB
anthropic              ------------------------------ 158.01 KiB/349.09 KiB
langchain-core         ------------------------------ 236.99 KiB/458.91 KiB
ipython                ------------------------------ 445.67 KiB/604.41 KiB
openai                 ------------------------------ 142.88 KiB/985.14 KiB
⠹ Preparing packages... (10/22)2m------------ 4.11 MiB/6.89 MiB
anthropic              ------------------------------ 158.01 KiB/349.09 KiB
langchain-core         ------------------------------ 252.99 KiB/458.91 KiB
ipython                ------------------------------ 477.67 KiB/604.41 KiB
openai                 ------------------------------ 174.88 KiB/985.14 KiB
⠹ Preparing packages... (10/22)---------- 4.47 MiB/6.89 MiB
anthropic              ------------------------------ 174.01 KiB/349.09 KiB
langchain-core         ------------------------------ 413.10 KiB/458.91 KiB
ipython                ------------------------------ 557.67 KiB/604.41 KiB
openai                 ------------------------------ 270.88 KiB/985.14 KiB
⠸ Preparing packages... (17/22)---------- 6.44 MiB/6.89 MiB
anthropic              ------------------------------ 190.01 KiB/349.09 KiB
langchain-core         ------------------------------ 413.10 KiB/458.91 KiB
ipython                ------------------------------ 557.67 KiB/604.41 KiB
⠸ Preparing packages... (17/22)-------------- 270.88 KiB/985.14 KiB
anthropic              ------------------------------ 190.01 KiB/349.09 KiB
ipython                ------------------------------ 589.67 KiB/604.41 KiB
⠸ Preparing packages... (17/22)-------------- 302.88 KiB/985.14 KiB
anthropic              ------------------------------ 190.01 KiB/349.09 KiB
⠸ Preparing packages... (17/22)-------------- 334.88 KiB/985.14 KiB
anthropic              ------------------------------ 270.01 KiB/349.09 KiB
⠸ Preparing packages... (17/22)-------------- 424.56 KiB/985.14 KiB
⠸ Preparing packages... (17/22)-------------- 472.56 KiB/985.14 KiB
Prepared 22 packages in 531ms
Installed 116 packages in 634ms
+ about-time==4.2.1
+ aiohappyeyeballs==2.6.1
+ aiohttp==3.13.2
+ aiosignal==1.4.0
+ alive-progress==3.3.0
+ annotated-types==0.7.0
+ anthropic==0.72.0
+ anyio==4.11.0
+ appnope==0.1.4
+ asttokens==3.0.0
+ attrs==25.4.0
+ certifi==2025.10.5
+ cffi==2.0.0
+ charset-normalizer==3.4.4
+ click==8.3.0
+ comm==0.2.3
+ cryptography==46.0.3
+ dataclasses-json==0.6.7
+ debugpy==1.8.17
+ decorator==5.2.1
+ distro==1.9.0
+ docstring-parser==0.17.0
+ dotenv==0.9.9
+ executing==2.2.1
+ frozenlist==1.8.0
+ grandalf==0.8
+ graphemeu==0.7.2
+ h11==0.16.0
+ httpcore==1.0.9
+ httpx==0.28.1
+ httpx-sse==0.4.3
+ idna==3.11
+ ipykernel==7.1.0
+ ipython==9.7.0
+ ipython-pygments-lexers==1.1.1
+ jedi==0.19.2
+ jiter==0.11.1
+ jsonpatch==1.33
+ jsonpointer==3.0.0
+ jsonschema==4.25.1
+ jsonschema-specifications==2025.9.1
+ jupyter-client==8.6.3
+ jupyter-core==5.9.1
+ langchain==1.0.4
+ langchain-anthropic==1.0.1
+ langchain-classic==1.0.0
+ langchain-community==0.4.1
+ langchain-core==1.0.3
+ langchain-mcp-adapters==0.1.12
+ langchain-openai==1.0.2
+ langchain-text-splitters==1.0.0
+ langgraph==1.0.2
+ langgraph-checkpoint==3.0.1
+ langgraph-prebuilt==1.0.2
+ langgraph-sdk==0.2.9
+ langsmith==0.4.41
+ markdown-it-py==4.0.0
+ marshmallow==3.26.1
+ matplotlib-inline==0.2.1
+ mcp==1.21.0
+ mdurl==0.1.2
+ multidict==6.7.0
+ mypy-extensions==1.1.0
+ nest-asyncio==1.6.0
+ numpy==2.3.4
+ openai==2.7.1
+ orjson==3.11.4
+ ormsgpack==1.12.0
+ packaging==25.0
+ parso==0.8.5
+ pexpect==4.9.0
+ platformdirs==4.5.0
+ prompt-toolkit==3.0.52
+ propcache==0.4.1
+ psutil==7.1.3
+ ptyprocess==0.7.0
+ pure-eval==0.2.3
+ pycparser==2.23
+ pydantic==2.12.4
+ pydantic-core==2.41.5
+ pydantic-settings==2.11.0
+ pygments==2.19.2
+ pyjwt==2.10.1
+ pyparsing==3.2.5
+ python-dateutil==2.9.0.post0
+ python-dotenv==1.2.1
+ python-multipart==0.0.20
+ pyyaml==6.0.3
+ pyzmq==27.1.0
+ referencing==0.37.0
+ regex==2025.11.3
+ requests==2.32.5
+ requests-toolbelt==1.0.0
+ rich==14.2.0
+ rpds-py==0.28.0
+ six==1.17.0
+ sniffio==1.3.1
+ sqlalchemy==2.0.44
+ sse-starlette==3.0.3
+ stack-data==0.6.3
+ starlette==0.50.0
+ tavily-python==0.7.12
+ tenacity==9.1.2
+ tiktoken==0.12.0
+ tornado==6.5.2
+ tqdm==4.67.1
+ traitlets==5.14.3
+ typing-extensions==4.15.0
+ typing-inspect==0.9.0
+ typing-inspection==0.4.2
+ urllib3==2.5.0
+ uvicorn==0.38.0
+ wcwidth==0.2.14
+ xxhash==3.6.0
+ yarl==1.22.0
+ zstandard==0.25.0
	

	

		
from pathlib import Path
 
def get_current_dir() -> Path:
    """Get the current directory of the module.
 
    This function is compatible with Jupyter notebooks and regular Python scripts.
 
    Returns:
        Path object representing the current directory
    """
    try:
        return Path(__file__).resolve().parent
    except NameError: # __file__ is not defined
        return Path.cwd()
	
	

		
			
		
	
	
Copied

	

		
from datetime import datetime
 
def get_today_str() -> str:
    """Get current date in a human-readable format."""
    return datetime.now().strftime("%a %b %-d, %Y")
	
	

		
			
		
	
	
Copied

	

		
from rich.console import Console
from rich.panel import Panel
from rich.text import Text
import json
import ast
 
console = Console()
 
def format_tool_outputs(tool_outputs_list: list) -> str:
    """Format a list of ToolMessage objects into a readable string"""
    formatted_parts = []
    
    for i, output in enumerate(tool_outputs_list, 1):
        # Handle ToolMessage objects that have been converted to strings
        if isinstance(output, dict):
            formatted_parts.append(f"
  Tool Output {i}:")
            formatted_parts.append(f"    Name: {output.get('name', 'N/A')}")
            formatted_parts.append(f"    Tool Call ID: {output.get('tool_call_id', 'N/A')}")
            
            # Format the content (which contains the actual output)
            content = output.get('content', 'N/A')
            if isinstance(content, str):
                # Truncate very long outputs
                if len(content) > 500:
                    content_preview = content[:500] + f"... ({len(content)} chars total)"
                else:
                    content_preview = content
                formatted_parts.append(f"    Content:")
                # Indent each line of content
                for line in content_preview.split('
'):
                    formatted_parts.append(f"      {line}")
            else:
                formatted_parts.append(f"    Content: {content}")
        else:
            formatted_parts.append(f"
  Tool Output {i}: {output}")
    
    return "
".join(formatted_parts)
 
def format_string_with_structures(content: str) -> str:
    """
    Detect and format structured data (lists, dicts) within a string.
    Handles cases like 'Tool calls: [...]' and 'Tool outputs: [...]' by parsing and formatting the structure.
    """
    # Check if the string contains 'Tool outputs:' followed by a list
    if 'Tool outputs:' in content:
        try:
            # Find the position where the tool outputs list starts
            tool_outputs_index = content.index('Tool outputs:')
            prefix = content[:tool_outputs_index + len('Tool outputs:')]
            
            # Extract the part that should be a list
            potential_list = content[tool_outputs_index + len('Tool outputs:'):].strip()
            
            # Try to parse it as a Python literal (list/dict)
            parsed_data = ast.literal_eval(potential_list)
            
            # If it's a list of tool outputs, format them nicely
            if isinstance(parsed_data, list):
                formatted_parts = [prefix + "
"]
                formatted_parts.append(format_tool_outputs(parsed_data))
                return "
".join(formatted_parts)
        except (ValueError, SyntaxError):
            # If parsing fails, continue to next check
            pass
    
    # Check if the string contains 'Tool calls:' followed by a list
    if 'Tool calls:' in content:
        try:
            # Find the position where the tool calls list starts
            tool_calls_index = content.index('Tool calls:')
            prefix = content[:tool_calls_index + len('Tool calls:')]
            
            # Extract the part that should be a list
            potential_list = content[tool_calls_index + len('Tool calls:'):].strip()
            
            # Try to parse it as a Python literal (list/dict)
            parsed_data = ast.literal_eval(potential_list)
            
            # If it's a list of tool calls, format them nicely
            if isinstance(parsed_data, list):
                formatted_parts = [prefix + "
"]
                for i, tool_call in enumerate(parsed_data, 1):
                    if isinstance(tool_call, dict):
                        formatted_parts.append(f"
  Tool Call {i}:")
                        formatted_parts.append(f"    Name: {tool_call.get('name', 'N/A')}")
                        formatted_parts.append(f"    ID: {tool_call.get('id', 'N/A')}")
                        formatted_parts.append(f"    Type: {tool_call.get('type', 'N/A')}")
                        if 'args' in tool_call:
                            formatted_parts.append(f"    Args:")
                            formatted_parts.append(f"       {json.dumps(tool_call['args'], indent=7, ensure_ascii=False)}")
                return "
".join(formatted_parts)
        except (ValueError, SyntaxError):
            # If parsing fails, return the original content
            pass
    
    # Try to detect if the entire content is a JSON/dict/list
    try:
        # Try JSON first
        parsed = json.loads(content)
        return json.dumps(parsed, indent=2, ensure_ascii=False)
    except (json.JSONDecodeError, TypeError):
        try:
            # Try Python literal (ast.literal_eval)
            parsed = ast.literal_eval(content)
            return json.dumps(parsed, indent=2, ensure_ascii=False)
        except (ValueError, SyntaxError):
            # If all parsing attempts fail, return original content
            return content
 
def format_message_content(message):
    """Convert message content to displayable string"""
    parts = []
    tool_calls_processed = False
 
    # Handle ToolCall objects (special case - they don't have 'content')
    if isinstance(message, dict) and 'args' in message and 'name' in message:
        # This is a ToolCall dictionary
        parts.append(f"Tool Call Name: {message.get('name', 'N/A')}")
        parts.append(f"ID: {message.get('id', 'N/A')}")
        
        # Format the args (which should be the tool calls list)
        args = message.get('args', [])
        if isinstance(args, list):
            for i, tool_call in enumerate(args, 1):
                if isinstance(tool_call, dict):
                    parts.append(f"
  Tool Call {i}:")
                    parts.append(f"    Name: {tool_call.get('name', 'N/A')}")
                    parts.append(f"    ID: {tool_call.get('id', 'N/A')}")
                    parts.append(f"    Type: {tool_call.get('type', 'N/A')}")
                    if 'args' in tool_call:
                        parts.append(f"    Args:")
                        parts.append(f"       {json.dumps(tool_call['args'], indent=7, ensure_ascii=False)}")
        return "
".join(parts)
    
    # Check if message has 'content' attribute
    if not hasattr(message, 'content'):
        # If it's a dict-like object, try to access it as a dict
        if hasattr(message, '__getitem__'):
            try:
                content = message['content'] if 'content' in message else str(message)
                parts.append(content)
                return "
".join(parts)
            except (KeyError, TypeError):
                parts.append(str(message))
                return "
".join(parts)
        else:
            parts.append(str(message))
            return "
".join(parts)
    
    # Handle main content (normal messages with 'content' attribute)
    if isinstance(message.content, str):
        # Try to detect and format structured data within the string
        formatted_content = format_string_with_structures(message.content)
        parts.append(formatted_content)
    elif isinstance(message.content, list):
        # Handle complex content like tool calls (Anthropic format)
        for item in message.content:
            if item.get('type') == 'text':
                parts.append(item['text'])
            elif item.get('type') == 'tool_use':
                parts.append(f"
🔧 Tool Call: {item['name']}")
                parts.append(f"   Args: {str(json.dumps(item['input'], indent=7, ensure_ascii=False))}")
                parts.append(f"   ID: {item.get('id', 'N/A')}")
                tool_calls_processed = True
    else:
        parts.append(str(message.content))
    
    # Handle tool calls attached to the message (OpenAI format) - only if not already processed
    if not tool_calls_processed and hasattr(message, 'tool_calls') and message.tool_calls:
        for tool_call in message.tool_calls:
            parts.append(f"
🔧 Tool Call: {tool_call['name']}")
            parts.append(f"   Args: {json.dumps(tool_call['args'], indent=2)}")
            parts.append(f"   ID: {tool_call['id']}")
    
    return "
".join(parts)
 
def format_messages(messages, title: str = "", border_style: str = "white", msg_subtype: str = ""):
    """Format and display a list of messages with Rich formatting
    
    Args:
        messages: List of messages to format
        title: Title of the panel
        border_style: Border style of the panel
        msg_subtype: Subtype of the message
    """
    # Check if messages is a list
    if isinstance(messages, list):
        for m in messages:
            # Handle different message types
            if isinstance(m, dict):
                # Check if it's a ToolCall dict
                if 'args' in m and 'name' in m:
                    msg_type = 'ToolCall'
                else:
                    msg_type = 'Dict'
            else:
                msg_type = m.__class__.__name__.replace('Message', '')
            
            content = format_message_content(m)
 
            if msg_type == 'Human':
                if msg_subtype == 'RealHumanMessage':
                    if title == "":
                        title = "🧑 Real Human Message"
                    else:
                        title = f"🧑 {title}"
                    console.print(Panel(content, title=title, border_style="#201ADB")) # Blue
                else:
                    if title == "":
                        title = "🧑 Simulated Human Message"
                    else:
                        title = f"🧑 {title}"
                    console.print(Panel(content, title=title, border_style="#1A64DB")) # Blue
            elif msg_type == 'AI':
                if title == "":
                    title = "🤖 Assistant"
                else:
                    title = f"🤖 {title}"
                console.print(Panel(content, title=title, border_style="#24FA00")) # Green
            elif msg_type == 'ClarifyWithUser':
                if title == "":
                    title = "🤖 Clarify With User"
                else:
                    title = f"🤖 {title}"
                console.print(Panel(content, title=title, border_style="#37DB1A")) # Green
            elif msg_type == 'ResearchQuestion':
                if title == "":
                    title = "🤖 Research brief generated"
                else:
                    title = f"🤖 {title}"
                console.print(Panel(content, title=title, border_style="#37DB1A")) # Green
            elif msg_type == 'Tool':
                if title == "":
                    title = "🔧 Tool Output"
                else:
                    title = f"🔧 {title}"
                console.print(Panel(content, title=title, border_style="yellow"))
            elif msg_type == 'ToolCall':
                if title == "":
                    title = "🔧 Tool Calls"
                else:
                    title = f"🔧 {title}"
                console.print(Panel(content, title=title, border_style="magenta"))
            elif msg_type == 'Use tools':
                if title == "":
                    title = "🔧 Tool Output"
                else:
                    title = f"🔧 {title}"
                console.print(Panel(content, title=title, border_style="yellow"))
            elif msg_type == 'System':
                if title == "":
                    title = "🔧 System Message"
                else:
                    title = f"🔧 {title}"
                console.print(Panel(content, title=title, border_style="red"))
            else:
                print(f"msg_type: {msg_type}")
                if title == "":
                    title = f"📝 {msg_type}"
                else:
                    title = f"📝 {title}"
                console.print(Panel(content, title=title, border_style="white"))
    elif isinstance(messages, str):
        console.print(Panel(messages, title=title, border_style=border_style))
    else:
        print(f"messages type: {type(messages)}")
	
	

		
			
		
	
	
Copied

	

		
clarify_with_user_instructions="""
These are the messages that have been exchanged so far with the user requesting the report:
<Messages>
{messages}
</Messages>
 
Today's date is {date}.
 
Assess whether you need to ask any clarifying questions or whether the user has already provided you with enough information to begin the investigation.
IMPORTANT: If you see in the message history that you have already asked a clarifying question, it is almost always unnecessary to ask another one. Only ask another question if it is ABSOLUTELY NECESSARY.
 
If there are acronyms, abbreviations, or unfamiliar terms, ask the user to clarify them.
If you need to ask a question, follow these guidelines:
- Be concise when gathering all the necessary information.
- Make sure you gather all the information necessary to carry out the research task in a concise and well-structured manner.
 - Use bullet points or numbered lists if necessary for clarity. Make sure you use Markdown formatting and that it will display correctly if the output string is passed to a Markdown renderer.
 - Do not request unnecessary information or information that the user has already provided. If you see that the user has already provided the information, do not request it again.
 
Respond in valid JSON format with these exact keys:
“need_clarification”: boolean,
‘question’: “<question to ask the user to clarify the scope of the report>”,
“verification”: “<verification message that we will begin the investigation>”
 
If you need to ask a clarifying question, return:
“need_clarification”: true,
‘question’: “<your clarifying question>”,
“verification”: “”
 
If you do not need to ask a clarifying question, return:
“need_clarification”: false,
‘question’: “”,
“verification”: “<Confirmation message that you will now begin the investigation based on the information provided.>”
 
For the verification message when no clarification is needed:
- Confirm that you have enough information to proceed.
 - Briefly summarize the key aspects of what you understand from the request.
 - Confirm that the investigation process will now begin.
 - Keep the message concise and professional.
 
Always respond in the language in which the user has asked you. If in doubt, respond in English.
"""
	
	

		
			
		
	
	
Copied

	

		
transform_messages_into_research_topic_prompt = """You will be provided with a set of messages that have been exchanged between you and the user so far. 
Your job is to translate these messages into a more detailed and specific research question that will be used to guide the research.
 
The messages exchanged between you and the user so far are:
<Messages>
{messages}
</Messages>
 
Today's date is {date}.
 
You will return a single research question that will be used to guide the research.
 
Guidelines:
1. Maximize specificity and detail.
- Include all known user preferences and explicitly list key attributes or dimensions to consider.
- It is important that all user details are included in the instructions.
 
2. Treat unspecified dimensions with care
- When the quality of the research requires additional dimensions that the user has not specified to be considered, acknowledge them as open considerations rather than assumed preferences.
- Example: Instead of assuming “budget options,” say “consider all price ranges unless cost restrictions are specified.”
- Only mention dimensions that are truly necessary for thorough research in that area.
 
3. Avoid unjustified assumptions
- Never invent specific user preferences, restrictions, or requirements that have not been indicated.
- If the user has not provided a specific detail, explicitly point out this lack of specification.
- Guide the researcher to treat unspecified aspects as flexible rather than making assumptions.
 
4. Distinguish between the scope of the research and user preferences
- Scope of research: what topics/dimensions should be researched (may be broader than the user's explicit mentions)
- User preferences: specific restrictions, requirements, or preferences (you should only include what the user has indicated)
- Example: “Investigate the factors that influence coffee quality (including bean origin, roasting methods, and brewing techniques) in Madrid coffee shops, focusing primarily on flavor, as specified by the user.”
 
5. Use the first person
- Write the request from the user's perspective.
 
6. Sources
- If specific sources should be prioritized, then specify them in the research question.
- For product and travel research, it is preferable to link directly to official or primary websites (e.g., official brand websites, manufacturer pages, or reputable e-commerce platforms such as Amazon for user reviews) rather than aggregator sites or blogs with heavy SEO.
- For academic or scientific queries, it is preferable to link directly to the original article or official journal publication, rather than to survey articles or secondary abstracts.
- For individuals, try to link directly to their LinkedIn profile, personal website, or GitHub profile, if they have one.
- If the query is in a specific language, prioritize sources published in that language.
 
Always respond in the language in which the user asked you the question. If in doubt, respond in English.
"""
	
	

		
			
		
	
	
Copied

	

		
import operator
from typing_extensions import Optional, Annotated, Sequence
 
from langchain_core.messages import BaseMessage
from langgraph.graph import MessagesState
from langgraph.graph.message import add_messages
 
class AgentInputState(MessagesState):
    """Input state for the full agent - only contains messages from user input."""
    pass
 
class AgentState(MessagesState):
    """
    Main state for the full multi-agent research system.
 
    Extends MessagesState with additional fields for research coordination.
    Note: Some fields are duplicated across different state classes for proper
    state management between subgraphs and the main workflow.
    """
 
    # Research brief generated from user conversation history
    research_brief: Optional[str]
    # Messages exchanged with the supervisor agent for coordination
    supervisor_messages: Annotated[Sequence[BaseMessage], add_messages]
    # Raw unprocessed research notes collected during the research phase
    raw_notes: Annotated[list[str], operator.add] = []
    # Processed and structured notes ready for report generation
    notes: Annotated[list[str], operator.add] = []
    # Final formatted research report
    final_report: str
	
	

		
			
		
	
	
Copied

state = {
"messages": ["Hello, how are you?"],
"research_brief": "Investigate the factors that influence coffee quality",
"supervisor_messages": [],
"raw_notes": [],
"notes": [],
"final_report": ""
}

agent.invoke(state)

	

		
from pydantic import BaseModel, Field
 
class ClarifyWithUser(BaseModel):
    """Schema for user clarification decision and questions."""
 
    need_clarification: bool = Field(
        description="Whether the user needs to be asked a clarifying question.",
    )
    question: str = Field(
        description="A question to ask the user to clarify the report scope",
    )
    verification: str = Field(
        description="Verify message that we will start research after the user has provided the necessary information.",
    )
 
class ResearchQuestion(BaseModel):
    """Schema for structured research brief generation."""
 
    research_brief: str = Field(
        description="A research question that will be used to guide the research.",
    )
	
	

		
			
		
	
	
Copied

	

		
from langchain.chat_models import init_chat_model
import os
import dotenv
 
dotenv.load_dotenv()
 
SCOPE_MODEL_NAME = "gpt-4.1"
SCOPE_MODEL_PROVIDER = "openai"
SCOPE_MODEL_BASE_URL = "https://api.openai.com/v1"
SCOPE_MODEL_TEMPERATURE = 0.0
SCOPE_MODEL_PROVIDER_API_KEY = os.getenv("OPENAI_API_KEY")
 
scope_model = init_chat_model(
    model=SCOPE_MODEL_NAME,
    model_provider=SCOPE_MODEL_PROVIDER,
    api_key=SCOPE_MODEL_PROVIDER_API_KEY,
    base_url=SCOPE_MODEL_BASE_URL,
    temperature=SCOPE_MODEL_TEMPERATURE
)
	
	

		
			
		
	
	
Copied

	

		
from typing_extensions import Literal
from alive_progress import alive_bar
import traceback
import sys
 
from langchain_core.messages import HumanMessage, AIMessage, SystemMessage, get_buffer_string
from langgraph.graph import START, END
from langgraph.types import Command
 
def clarify_with_user(state: AgentState) -> Command[Literal["write_research_brief", "__end__"]]:
    """
    Determine if the user's request contains sufficient information to proceed with research.
    
    Uses structured output to make deterministic decisions and avoid hallucination.
    Routes to either research brief generation or ends with a clarification question.
    """
 
    try:
        print("⏳ Scope agent:")
        format_messages([state.get("messages", [])[-1]], title="Real Human Message", msg_subtype='RealHumanMessage')
 
        # Set up structured output model
        structured_output_model = scope_model.with_structured_output(ClarifyWithUser)
 
        # Invoke the model with clarification instructions
        with alive_bar(monitor=False, stats=False, title="", spinner='dots_waves', bar='blocks') as bar:
            response = structured_output_model.invoke([
                HumanMessage(content=clarify_with_user_instructions.format(
                    messages=get_buffer_string(messages=state["messages"]),
                    date=get_today_str()
                ))
            ])
            bar()
        
        # Format and display the research messages
        format_messages([response], title="Scope Assistant - need clarification?")
        
        # Route based on clarification need
        if response.need_clarification:
            # Create a System message to show the decision
            routing_message = SystemMessage(
                content="Necesita aclaración por parte del usuario. Enviando pregunta aclaratoria..."
            )
            format_messages([routing_message], title="Scope System Message")
            return Command(
                goto=END,
                update={"messages": [AIMessage(content=response.question)]}
            )
        else:
            # Create a System message to show the decision
            routing_message = SystemMessage(
                content="No necesita aclaración por parte del usuario. Enviando mensaje de verificación..."
            )
            format_messages([routing_message], title="Scope System Message")
            return Command(
                goto="write_research_brief",
                update={"messages": [AIMessage(content=response.verification)]}
            )
    
    except Exception as e:
        # Get the traceback information
        exc_type, exc_obj, exc_tb = sys.exc_info()
        line_number = exc_tb.tb_lineno
        
        # Print detailed error information
        print(f"
❌ Error in clarify_with_user function:")
        print(f"   Line number: {line_number}")
        print(f"   Error type: {type(e).__name__}")
        print(f"   Error message: {str(e)}")
        print(f"
   Full traceback:")
        traceback.print_exc()
        
        # Re-raise the exception to let the caller handle it
        raise
	
	

		
			
		
	
	
Copied

	

		
def write_research_brief(state: AgentState):
    """
    Transform the conversation history into a comprehensive research brief.
    
    Uses structured output to ensure the brief follows the required format
    and contains all necessary details for effective research.
    """
    
    try:
        # Set up structured output model
        structured_output_model = scope_model.with_structured_output(ResearchQuestion)
 
        print("⏳ Scope agent - Write research brief:")
        format_messages([state.get("messages", [])[-1]], title="Scope Assistant - Write research brief")
        
        # Generate research brief from conversation history
        with alive_bar(monitor=False, stats=False, title="", spinner='dots_waves', bar='blocks') as bar:
            response = structured_output_model.invoke([
                HumanMessage(content=transform_messages_into_research_topic_prompt.format(
                    messages=get_buffer_string(state.get("messages", [])),
                    date=get_today_str()
                ))
            ])
            bar()
        
        # Format and display the research brief
        format_messages([response], title="Scope Assistant - Research brief generated")
        
        # Update state with generated research brief and pass it to the supervisor
        return {
            "research_brief": response.research_brief,
            "supervisor_messages": [HumanMessage(content=f"{response.research_brief}.")]
        }
    
    except Exception as e:
        # Get the traceback information
        exc_type, exc_obj, exc_tb = sys.exc_info()
        line_number = exc_tb.tb_lineno
        
        # Print detailed error information
        print(f"
❌ Error in write_research_brief function:")
        print(f"   Line number: {line_number}")
        print(f"   Error type: {type(e).__name__}")
        print(f"   Error message: {str(e)}")
        print(f"
   Full traceback:")
        traceback.print_exc()
        
        # Re-raise the exception to let the caller handle it
        raise
	
	

		
			
		
	
	
Copied

	

		
from langgraph.graph import StateGraph
 
# Build the scoping workflow
scope_graph_builder = StateGraph(AgentState, input_schema=AgentInputState)
	
	

		
			
		
	
	
Copied

	

		
# Add workflow nodes
scope_graph_builder.add_node("clarify_with_user", clarify_with_user)
scope_graph_builder.add_node("write_research_brief", write_research_brief)
	
	

		
			
		
	
	
Copied

	

		
<langgraph.graph.state.StateGraph at 0x10f325610>
	

	

		
from langgraph.graph import START, END
 
# Add workflow edges
scope_graph_builder.add_edge(START, "clarify_with_user")
scope_graph_builder.add_edge("write_research_brief", END)
	
	

		
			
		
	
	
Copied

	

		
<langgraph.graph.state.StateGraph at 0x10f325610>
	

	

		
from langgraph.checkpoint.memory import InMemorySaver
from IPython.display import Image, display
 
checkpointer = InMemorySaver()
scope_agent = scope_graph_builder.compile(checkpointer=checkpointer)
 
# Visualize the workflow
display(Image(scope_agent.get_graph(xray=True).draw_mermaid_png()))
	
	

		
			
		
	
	
Copied

	

		
<IPython.core.display.Image object>
	

	

		
thread = {"configurable": {"thread_id": "1"}}
user_message = "I want to investigate the best cafes in Madrid."
 
result = await scope_agent.ainvoke({"messages": [HumanMessage(content=f"{user_message}.")]}, config=thread)
	
	

		
			
		
	
	
Copied

	

		
⏳ Scope agent:
	

	

		
╭───────────────────────────────────────────── 🧑 Real Human Message ─────────────────────────────────────────────╮
│ I want to investigate the best cafes in Madrid..                                                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
	

	

		
|▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉| in 3.1s
	

	

		
╭─────────────────────────────────── 🤖 Scope Assistant - need clarification? ────────────────────────────────────╮
│ need_clarification=True question="Could you please clarify what you mean by 'best'? Are you looking for cafes   │
│ with the best coffee, best atmosphere, best for working, or something else? Also, do you have any preferences   │
│ regarding location, price range, or type of cafe (e.g., specialty coffee, traditional, brunch spots)?"          │
│ verification=''                                                                                                 │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
	

	

		
╭──────────────────────────────────────────── 🔧 Scope System Message ────────────────────────────────────────────╮
│ Necesita aclaración por parte del usuario. Enviando pregunta aclaratoria...                                     │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
	

	

		
user_message = "Examine the quality of coffee to evaluate the best cafes in Madrid."
 
result = await scope_agent.ainvoke({"messages": [HumanMessage(content=f"{user_message}.")]}, config=thread)
	
	

		
			
		
	
	
Copied

	

		
⏳ Scope agent:
	

	

		
╭───────────────────────────────────────────── 🧑 Real Human Message ─────────────────────────────────────────────╮
│ Examine the quality of coffee to evaluate the best cafes in Madrid..                                            │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
	

	

		
|▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉| in 1.8s
	

	

		
╭─────────────────────────────────── 🤖 Scope Assistant - need clarification? ────────────────────────────────────╮
│ need_clarification=False question='' verification='Thank you for clarifying your request. You would like an     │
│ investigation into the best cafes in Madrid, specifically evaluating them based on the quality of their coffee. │
│ I will now begin the investigation focusing on cafes in Madrid renowned for their coffee quality.'              │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
	

	

		
╭──────────────────────────────────────────── 🔧 Scope System Message ────────────────────────────────────────────╮
│ No necesita aclaración por parte del usuario. Enviando mensaje de verificación...                               │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
	

	

		
⏳ Scope agent - Write research brief:
	

	

		
╭─────────────────────────────────── 🤖 Scope Assistant - Write research brief ───────────────────────────────────╮
│ Thank you for clarifying your request. You would like an investigation into the best cafes in Madrid,           │
│ specifically evaluating them based on the quality of their coffee. I will now begin the investigation focusing  │
│ on cafes in Madrid renowned for their coffee quality.                                                           │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
	

	

		
|▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉| in 4.4s
	

	

		
╭───────────────────────────────── 🤖 Scope Assistant - Research brief generated ─────────────────────────────────╮
│ research_brief='I want to identify and evaluate the best cafes in Madrid based specifically on the quality of   │
│ their coffee. My primary criterion is coffee quality, which should include factors such as bean origin,         │
│ roasting methods, brewing techniques, and taste/flavor profile. I have not specified preferences regarding      │
│ location within Madrid, price range, type of cafe (e.g., specialty, traditional, brunch spots), or atmosphere,  │
│ so please consider cafes across all neighborhoods, price points, and styles unless further restrictions are     │
│ provided. Prioritize information from official cafe websites, reputable coffee review platforms, and direct     │
│ user reviews where available. The goal is to create a detailed, up-to-date list of Madrid cafes that are most   │
│ highly regarded for the quality of their coffee.'                                                               │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
	

If we recall what the architecture of the deep researcher was going to be like, we see that there is a Research supervisor who is responsible for assigning research tasks to different Researchers

	

		
research_agent_prompt = """You are a research assistant conducting research on the topic entered by the user. For context, today is {date}.
 
<Task>
Your job is to use tools to gather information on the topic entered by the user.
You can use any of the tools provided to find resources that will help you answer the research question. You can use these tools in series or in parallel; your research is carried out in a tool call loop.
</Task>
 
<Available Tools>
You have access to two main tools:
1. **tavily_search**: to perform web searches to gather information.
2. **think_tool**: for reflection and strategic planning during research.
 
**IMPORTANT: use think_tool after each search to reflect on the results and plan the next steps**.
**CRITICAL: You must always provide the ‘reflection’ parameter with detailed content when calling think_tool. Never call this tool without arguments.**
</Available Tools>
 
<Instructions>
Think like a human researcher with limited time. Follow these steps:
 
1. **Read the question carefully:** What specific information does the user need?
2. **Start with broader searches**: use broad, comprehensive queries first.
3. **After each search, pause and evaluate**: do I have enough to answer? What am I missing?
4. **Perform more specific searches as you gather information**: fill in the gaps.
5. **Stop when you can answer with confidence**: don't keep searching for perfection.
</Instructions>
 
<Hard Limits>
**Tool call budgets** (avoid excessive searching):
- **Simple queries**: use a maximum of 2-3 search tool calls.
- **Complex queries**: use a maximum of 5 search tool calls
- **Always stop**: after 5 search tool calls if you cannot find suitable sources
 
**Stop immediately when**:
- You can answer the user's question comprehensively
- You have more than 3 examples/sources relevant to the question
- Your last 2 searches have returned similar information
</Hard Limits>
 
<Show Your Thinking>
After each search tool call, use think_tool to analyze the results:
- What key information have I found?
- What is missing?
- Do I have enough to answer the question thoroughly?
- Should I continue searching or give my answer?
</Show Your Thinking>
"""
	
	

		
			
		
	
	
Copied

	

		
summarize_webpage_prompt = """Your task is to summarize the raw content of a web page obtained through an Internet search. Your goal is to create a summary that retains the most important information from the original web page. This summary will be used by a subsequent research agent, so it is essential to retain key details without losing essential information.
 
This is the raw content of the web page:
 
<webpage_content>
{webpage_content}
</webpage_content>
 
Follow these guidelines to create your summary:
 
1. Identify and retain the main topic or purpose of the web page.
2. Retain data, statistics, and key points that are fundamental to the message of the content.
3. Retain important quotes from reliable sources or experts.
4. Maintain the chronological order of events if the content is time-sensitive or historical.
5. Retain lists or step-by-step instructions, if any.
6. Include relevant dates, names, and places that are crucial to understanding the content.
7. Summarize long explanations while keeping the main message intact.
 
When dealing with different types of content:
 
- For news articles: focus on who, what, when, where, why, and how.
- For scientific content: retain the methodology, results, and conclusions.
- For opinion pieces: keep the main arguments and supporting points.
- For product pages: keep the key features, specifications, and unique selling points.
 
Your summary should be significantly shorter than the original content, but comprehensive enough to stand as a source of information on its own. Aim for 25% to 30% of the original length, unless the content is already concise.
 
Present your summary in the following format:
 
```
{{
   “summary”: “Your summary here, structured with appropriate paragraphs or bullet points as needed”,
   “key_excerpts”: “First quote or important excerpt, Second quote or important excerpt, Third quote or important excerpt, ...Add more excerpts as needed, up to a maximum of 5”
}}
```
 
Here are two examples of good summaries:
 
Example 1 (for a news article):
```json
{{
   “summary”: "On July 15, 2023, NASA successfully launched the Artemis II mission from the Kennedy Space Center. This is the first manned mission to the Moon since Apollo 17 in 1972. The four-person crew, led by Commander Jane Smith, will orbit the Moon for 10 days before returning to Earth. This mission is a crucial step in NASA's plans to establish a permanent human presence on the Moon by 2030."
   “key_excerpts”: "Artemis II represents a new era in space exploration, said NASA Administrator John Doe. The mission will test critical systems for future long-duration stays on the Moon, explained Chief Engineer Sarah Johnson. We're not just going back to the Moon, we're going to the Moon, Commander Jane Smith said during the pre-launch press conference."
}}
```
 
Example 2 (for a scientific article):
```json
{{
   “summary”: "A new study published in Nature Climate Change reveals that sea levels are rising faster than previously thought. Researchers analyzed satellite data from 1993 to 2022 and found that the rate of sea level rise has accelerated by 0.08 mm/year² over the past three decades. This acceleration is mainly attributed to the melting of the Greenland and Antarctic ice sheets. The study predicts that if current trends continue, global sea levels could rise by up to 2 meters by 2100, posing a significant risk to coastal communities around the world.
   “key_excerpts”: “Our findings indicate a clear acceleration in sea level rise, which has important implications for coastal planning and adaptation strategies,” said lead author Dr. Emily Brown. The rate of ice sheet melt in Greenland and Antarctica has tripled since the 1990s, according to the study. Without immediate and substantial reductions in greenhouse gas emissions, we face a potentially catastrophic sea level rise by the end of this century, warned co-author Professor Michael Green.  
}}
```
 
Remember that your goal is to create a summary that can be easily understood and used by a subsequent research agent, while retaining the most important information from the original web page.
 
Today's date is {date}.
"""
	
	

		
			
		
	
	
Copied

	

		
compress_research_system_prompt = """You are a research assistant who has researched a topic using various tools and Internet searches. Your job now is to clean up the results, retaining all relevant statements and information gathered by the researcher. To provide context, today is {date}.
 
<Task>
You must clean up the information gathered from the tools and internet searches in the existing messages.
All relevant information should be repeated and rewritten verbatim, but in a cleaner format.
The goal of this step is simply to remove any obviously irrelevant or duplicate information.
For example, if three sources say “X,” you could say “These three sources claim X.”
Only these complete and clean results will be returned to the user, so it is essential that you do not lose any information from the raw messages.
</Task>
 
<Tool Call Filtering>
**IMPORTANT**: When processing research messages, focus only on the substantive content of the research:
- **Include**: All tavily_search results and web search findings
- **Exclude**: think_tool calls and responses, as these are the agent's internal reflections for decision-making and should not be included in the final investigation report
- **Focus on**: the actual information gathered from external sources, not the agent's internal reasoning process.
 
Calls to think_tool contain strategic reflections and notes on decision-making that are internal to the investigation process, but do not contain factual information that should be retained in the final report.
</Tool Call Filtering>
 
<Guidelines>
1. The results should be comprehensive and include ALL information and sources that the researcher has gathered from tool calls and web searches. You are expected to repeat key information verbatim.
2. This report may be as long as necessary to include ALL information that the researcher has gathered.
3. In your report, you must include inline citations for each source that the researcher has found.
4. You must include a “Sources” section at the end of the report listing all sources found by the researcher with corresponding citations, referenced in relation to the statements in the report.
5. Be sure to include ALL sources collected by the researcher in the report and how they were used to answer the question.
6. It is very important not to lose any sources. An LLM will be used later to merge this report with others, so it is essential to have all sources available.
</Guidelines>
 
<Output Format>
The report should be structured as follows:
**List of queries and tool calls made**
**Complete results**
**List of all relevant sources (with citations in the report)**
</Output Format>
 
<Citation Rules>
- Assign each unique URL a unique citation number in your text.
- End with ### Sources, listing each source with the corresponding numbers.
- IMPORTANT: Number the sources sequentially without gaps (1, 2, 3, 4...) in the final list, regardless of the sources you choose.
- Example format:
  [1] Source title: URL
  [2] Source title: URL
</Citation Rules>
 
Important reminder: It is extremely important that any information that is remotely relevant to the user's research topic is preserved verbatim (i.e., do not rewrite it, do not summarize it, do not paraphrase it).
 
Today's date is {date}.
"""
	
	

		
			
		
	
	
Copied

	

		
compress_research_human_message = """All previous messages refer to research conducted by an AI researcher on the following research topic:
 
RESEARCH TOPIC: {research_topic}
 
Your task is to refine the results of this research while retaining ALL information relevant to answering this specific research question.
 
FUNDAMENTAL REQUIREMENTS:
- DO NOT summarize or paraphrase the information: keep it verbatim.
- DO NOT lose any specific details, data, names, numbers, or findings.
- DO NOT filter out information that seems relevant to the research topic
- Organize the information in a clearer format, but keep all the content
- Include ALL sources and citations found during the research
- Remember that this research was conducted to answer the specific question above
 
The refined results will be used to prepare the final report, so it is essential that they be comprehensive."""
	
	

		
			
		
	
	
Copied

	

		
from typing_extensions import TypedDict, Annotated, List, Sequence
 
class ResearcherState(TypedDict):
    """
    State for the research agent containing message history and research metadata.
    
    This state tracks the researcher's conversation, iteration count for limiting
    tool calls, the research topic being investigated, compressed findings,
    and raw research notes for detailed analysis.
    """
    researcher_messages: Annotated[Sequence[BaseMessage], add_messages]
    tool_call_iterations: int
    research_topic: str
    compressed_research: str
    raw_notes: Annotated[List[str], operator.add]
 
class ResearcherOutputState(TypedDict):
    """
    Output state for the research agent containing final research results.
    
    This represents the final output of the research process with compressed
    research findings and all raw notes from the research process.
    """
    compressed_research: str
    raw_notes: Annotated[List[str], operator.add]
    researcher_messages: Annotated[Sequence[BaseMessage], add_messages]
	
	

		
			
		
	
	
Copied

	

		
class Summary(BaseModel):
    """Schema for webpage content summarization."""
    summary: str = Field(description="Concise summary of the webpage content")
    key_excerpts: str = Field(description="Important quotes and excerpts from the content")
	
	

		
			
		
	
	
Copied

	

		
def tavily_search_multiple(
    search_queries: List[str],
    max_results: int = 3,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = True,
) -> List[dict]:
    """Perform search using Tavily API for multiple queries.
 
    Args:
        search_queries: List of search queries to execute
        max_results: Maximum number of results per query
        topic: Topic filter for search results
        include_raw_content: Whether to include raw webpage content
 
    Returns:
        List of search result dictionaries
    """
    
    # Execute searches sequentially. Note: yon can use AsyncTavilyClient to parallelize this step.
    search_docs = []
    for query in search_queries:
        result = tavily_client.search(
            query,
            max_results=max_results,
            include_raw_content=include_raw_content,
            topic=topic
        )
        search_docs.append(result)
 
    return search_docs
	
	

		
			
		
	
	
Copied

	

		
def deduplicate_search_results(search_results: List[dict]) -> dict:
    """Deduplicate search results by URL to avoid processing duplicate content.
    
    Args:
        search_results: List of search result dictionaries
        
    Returns:
        Dictionary mapping URLs to unique results
    """
    unique_results = {}
    
    for response in search_results:
        for result in response['results']:
            url = result['url']
            if url not in unique_results:
                unique_results[url] = result
    
    return unique_results
	
	

		
			
		
	
	
Copied

	

		
def summarize_webpage_content(webpage_content: str) -> str:
    """Summarize webpage content using the configured summarization model.
    
    Args:
        webpage_content: Raw webpage content to summarize
        
    Returns:
        Formatted summary with key excerpts
    """
    try:
        # Set up structured output model for summarization
        structured_model = summarization_model.with_structured_output(Summary)
        
        # Generate summary
        summary = structured_model.invoke([
            HumanMessage(content=summarize_webpage_prompt.format(
                webpage_content=webpage_content,
                date=get_today_str()
            ))
        ])
        
        # Format summary with clear structure
        formatted_summary = (
            f"<summary>
{summary.summary}
</summary>

"
            f"<key_excerpts>
{summary.key_excerpts}
</key_excerpts>"
        )
        
        return formatted_summary
        
    except Exception as e:
        print(f"Failed to summarize webpage: {str(e)}")
        return webpage_content[:1000] + "..." if len(webpage_content) > 1000 else webpage_content
	
	

		
			
		
	
	
Copied

	

		
def process_search_results(unique_results: dict) -> dict:
    """Process search results by summarizing content where available.
    
    Args:
        unique_results: Dictionary of unique search results
        
    Returns:
        Dictionary of processed results with summaries
    """
    summarized_results = {}
    
    for url, result in unique_results.items():
        # Use existing content if no raw content for summarization
        if not result.get("raw_content"):
            content = result['content']
        else:
            # Summarize raw content for better processing
            content = summarize_webpage_content(result['raw_content'])
        
        summarized_results[url] = {
            'title': result['title'],
            'content': content
        }
    
    return summarized_results
	
	

		
			
		
	
	
Copied

	

		
def format_search_output(summarized_results: dict) -> str:
    """Format search results into a well-structured string output.
    
    Args:
        summarized_results: Dictionary of processed search results
        
    Returns:
        Formatted string of search results with clear source separation
    """
    if not summarized_results:
        return "No valid search results found. Please try different search queries or use a different search API."
    
    formatted_output = "Search results: 

"
    
    for i, (url, result) in enumerate(summarized_results.items(), 1):
        formatted_output += f"

--- SOURCE {i}: {result['title']} ---
"
        formatted_output += f"URL: {url}

"
        formatted_output += f"SUMMARY:
{result['content']}

"
        formatted_output += "-" * 80 + "
"
    
    return formatted_output
	
	

		
			
		
	
	
Copied

	

		
from langchain_core.tools import tool, InjectedToolArg
 
@tool(parse_docstring=True)
def tavily_search(
    query: str,
    max_results: Annotated[int, InjectedToolArg] = 3,
    topic: Annotated[Literal["general", "news", "finance"], InjectedToolArg] = "general",
) -> str:
    """Fetch results from Tavily search API with content summarization.
 
    Args:
        query: A single search query to execute
        max_results: Maximum number of results to return
        topic: Topic to filter results by ('general', 'news', 'finance')
    """
    # Execute search for single query
    search_results = tavily_search_multiple(
        [query], # Convert single query to list for the internal function
        max_results=max_results,
        topic=topic,
        include_raw_content=True,
    )
 
    # Deduplicate results by URL to avoid processing duplicate content
    unique_results = deduplicate_search_results(search_results)
 
    # Process results with summarization
    summarized_results = process_search_results(unique_results)
 
    # Format output for consumption
    return format_search_output(summarized_results)
	
	

		
			
		
	
	
Copied