Agentic Workflows with LangGraph

This repo implements reusable agent patterns in Python/LangGraph, with minimal domain-specific changes (prompts + tools). We emphasize a reflection pattern (plan → act → reflect(loop)) that can be adapted to different tasks by swapping prompts and toolsets.

Patterns covered

• Reflection Pattern (current default): LLM drafts, optionally calls tools, then a reflection node critiques/decides if it’s done.
• ReAct-style: Plan/reason, call tools, observe, repeat. Reflection is optional but can be added.
• Planner Pattern: A planner produces a high-level plan; executor/tool nodes carry it out (not the current default but noted for contrast).

Design decisions

• Single graph, domain by config: Same LangGraph structure across domains; only prompts and tools differ.
• Explicit state: Message history, tool calls, and reflection live in the graph state and are streamed for debugging.
• Tool abstraction: Tools are generic callables (e.g., ddg_search_tool, calculator_tool) so you can swap them without changing graph wiring.
• Rate-limit awareness: Prompts nudge the model to minimize searches; recursion limits cap runaway loops. Local LLM fallback is supported in code, but you can run Gemini-only if desired.
• Logging/observability: stream_mode="updates" prints each node/state transition to understand reasoning and tool usage.

Current demo agents

Travel Planner (reflection pattern)

• Goal: 2-day food-focused itinerary with rough budget.
• Prompts: Travel-specific, instructs minimal tool use, single reflection pass.
• Tools: ddg_search_tool, calculator_tool (search often not needed for the canned Lisbon demo).
• Behavior:
  • [agent] drafts the itinerary (reasoning/planning).
  • (Optional) tool calls if needed.
  • [reflect] critiques; if “More work is needed: no,” we emit the draft.
• Output: Concise itinerary with day-by-day plan, rough costs, and transit hints. Final answer printed from the agent draft.

Research Helper (reflection pattern)

• Goal: Source-backed summary (e.g., semaglutide findings).
• Prompts: Limit to 1–2 searches, cite titles/links, one reflection pass.
• Tools: ddg_search_tool.
• Behavior:
  • [agent] may call web_search, incorporates snippets.
  • [reflect] checks sufficiency; if lacking, says what to search next.
• Output: Concise answer with sources; fallback run if the streamed draft is blank.

How it maps to the criteria

• Accepts natural-language goal.
• Maintains explicit state (messages, tool calls, reflection).
• Reasoning/planning step in the agent node.
• Executes tools based on current state (ddg_search_tool, calculator_tool).
• Uses graph cycles: agent → tools → agent → reflect.
• Reflection/quality check via a dedicated node/prompt.
• Terminates when the agent deems the goal satisfied (recursion limit is just a guard).
• Swappable prompts/tools per domain; graph structure unchanged.

Swapping domains (prompts/tools only)

• Prompts: Edit the ReactPrompts (system/reflect/finalize) in each app runner.
• Tools: Adjust the tools = [...] list when building the agent; the graph wiring stays the same.
• LLM provider: LLM_PROVIDER env (gemini or local), GEMINI_MODEL, LOCAL_LLM_MODEL.

Running the demos

Travel Planner

python -m apps.travel_planner.run

• Streams node/state logs; prints final itinerary from the agent draft.
• Streams node/state logs; prints final answer (or runs a final pass if the draft was blank).

Notes on rate limits

• Prompts encourage fewer searches; reflection is single-pass.
• Recursion limits are modest to avoid tool-call loops.
• To avoid quotas entirely while testing, set LLM_PROVIDER=local and ensure your local model is configured.
• The DuckDuckGo rename warning is benign; switch to ddgs to silence it.