chore: langraph Research Assistant Agent

python/README.md

@@ -1,8 +1,15 @@
-# Travel Planning Agent (Python)
+# AI Agent Examples (Python)
 
-A travel planning AI agent built with the OpenAI Agents SDK and Traceloop for observability. This agent creates detailed travel itineraries using real-world APIs.
+Two production-quality AI agents demonstrating different agent frameworks with OpenTelemetry instrumentation via Traceloop:
 
-## Features
+1. **Travel Planning Agent** - OpenAI Agents SDK
+2. **Research Assistant Agent** - LangGraph
+
+Both agents use real-world APIs and are designed for debugging and testing observability instrumentation.
+
+## 1. Travel Planning Agent (OpenAI Agents SDK)
+
+### Features
 
 - **6 Tools** for comprehensive travel planning:
   - `search_destinations` - Find destinations by region using REST Countries API
@@ -16,6 +23,74 @@ A travel planning AI agent built with the OpenAI Agents SDK and Traceloop for ob
 - **Structured Output** using Pydantic models for type-safe itineraries
 - **Async Architecture** for efficient API calls
 
+### Usage
+
+```bash
+# Run a single query
+uv run python travel_agent.py
+
+# Run multiple queries
+uv run python travel_agent.py --count 5
+
+# Customize delay between queries
+uv run python travel_agent.py --count 3 --delay 3.0
+```
+
+### Example Queries
+
+- **Specific**: "Plan a 7-day luxury trip to Tokyo for couples interested in food"
+- **Broad**: "I want to explore Europe in summer. Find good destinations"
+- **Vague**: "I need a vacation. I like history. Plan something for me"
+- **Comparison**: "Should I visit Paris or Rome? Compare and create an itinerary"
+
+## 2. Research Assistant Agent (LangGraph)
+
+### Features
+
+- **5 Tools** for comprehensive research:
+  - `web_search` - DuckDuckGo search for current information
+  - `analyze_content` - Multi-type content analysis (summary, sentiment, technical)
+  - `extract_data` - Structured data extraction (facts, numbers, dates, entities)
+  - `compare_sources` - Source comparison and agreement/disagreement analysis
+  - `generate_report` - Formatted research reports (markdown, JSON, text)
+
+- **Complex State Management** with LangGraph StateGraph
+- **Conditional Routing** based on iteration count and research depth
+- **Memory Checkpointing** for workflow persistence
+- **Multi-step Reasoning** with iterative refinement
+
+### Usage
+
+```bash
+# Run with random research queries
+uv run python research_assistant.py --count 3
+
+# Run a specific query
+uv run python research_assistant.py --query "What are the latest developments in quantum computing?"
+
+# Customize delay between queries
+uv run python research_assistant.py --count 5 --delay 2.0
+```
+
+### Example Queries
+
+- **Information**: "What are the latest developments in artificial intelligence?"
+- **Comparison**: "Compare Python and JavaScript for web development"
+- **Analysis**: "Analyze the impact of social media on mental health"
+- **Technical**: "Explain how blockchain technology works and its applications"
+
+### Architecture
+
+```
+User Query → StateGraph → Agent Node (decides action)
+                            ↓
+                    Conditional Router
+                    ↓            ↓
+              Tool Node    Summarize Node
+                    ↓            ↓
+              Back to Agent    Final Output
+```
+
 ## Prerequisites
 
 - Python 3.11+
@@ -34,46 +109,42 @@ export OPENAI_API_KEY="your-openai-api-key"
 export TRACELOOP_API_KEY="your-traceloop-api-key"  # Optional
 ```
 
-## Usage
+## Quick Start
 
 ```bash
-# Run a single query
-uv run python travel_agent.py
+# Run travel planning agent
+uv run python travel_agent.py --count 3
 
-# Run multiple queries
-uv run python travel_agent.py --count 5
+# Run research assistant agent
+uv run python research_assistant.py --count 3
 
-# Customize delay between queries
-uv run python travel_agent.py --count 3 --delay 3.0
+# Run with custom query
+uv run python research_assistant.py --query "Your research question"
 ```
 
-## Example Queries
+## Comparison: OpenAI Agents SDK vs LangGraph
 
-The agent handles various request types:
+| Feature | OpenAI Agents SDK | LangGraph |
+|---------|-------------------|-----------|
+| **Complexity** | Simpler, higher-level API | More control, lower-level |
+| **State Management** | Automatic via Runner | Manual StateGraph definition |
+| **Routing** | Model-driven tool selection | Conditional edges & custom logic |
+| **Streaming** | Built-in event streaming | Stream through graph execution |
+| **Use Case** | Rapid prototyping, simpler flows | Complex workflows, fine control |
+| **Span Structure** | Linear tool call hierarchy | Graph-based nested spans |
 
-- **Specific**: "Plan a 7-day luxury trip to Tokyo for couples interested in food"
-- **Broad**: "I want to explore Europe in summer. Find good destinations"
-- **Vague**: "I need a vacation. I like history. Plan something for me"
-- **Comparison**: "Should I visit Paris or Rome? Compare and create an itinerary"
-
-## Output
+## Observability
 
-The agent produces structured itineraries including:
+Both agents are instrumented with OpenTelemetry via Traceloop SDK, capturing:
 
-- Trip title and overview
-- Day-by-day activities with times and locations
-- Meal recommendations
-- Accommodation suggestions
-- Travel tips
-- Packing suggestions
+- Tool invocations and parameters
+- API calls to external services
+- Model completions and token usage
+- State transitions (LangGraph)
+- Error handling and retries
+- End-to-end latency
 
-## Architecture
-
-```
-User Query → OpenAI Agents SDK → Tool Calls → External APIs → Structured Itinerary
-                    ↓
-             Traceloop (OpenTelemetry spans)
-```
+This makes them ideal for testing and debugging observability systems.
 
 ## License
 

python/pyproject.toml

@@ -11,6 +11,10 @@ dependencies = [
     "requests>=2.32.5",
     "python-dotenv>=1.2.1",
     "traceloop-sdk>=0.49.8",
+    "langgraph>=0.2.66",
+    "langchain>=0.3.20",
+    "langchain-openai>=0.3.9",
+    "ddgs>=1.0.0",
 ]
 
 [dependency-groups]
@@ -21,6 +25,7 @@ dev = [
 
 [project.scripts]
 travel-agent = "travel_agent:main"
+research-assistant = "research_assistant:main"
 
 [build-system]
 requires = ["hatchling"]