How shaunakbale/country-information-ai-agent works
This is a single-service Python application with a Streamlit UI that hosts a conversational AI agent. The agent uses LangGraph (ReAct pattern) to decide when to call a tool that fetches real-time country data from the RestCountries API, then synthesizes an answer using an LLM (Google Gemini by default, Azure OpenAI optional). Responses are streamed token-by-token to the UI, and Streamlit keeps session chat history.
• the UI ↔ agent runtime boundary,
• the agent graph + tool invocation loop,
• the two external dependencies (LLM provider + RestCountries),
• and the configuration/secrets (.env, optional LangSmith tracing).
Use these directories as your “authoritative components”:
Frontend (Streamlit UI)
• frontend/app.py
The entrypoint: renders chat UI, maintains conversation in session state, streams outputs.
Backend (agent, graph orchestration, tools, prompts, LLM adapters)
• backend/agents/country_information_agent.py
Likely where the agent is defined (system behavior, ReAct setup, tool wiring).
• backend/graph/graph.py, backend/graph/state.py, backend/graph/invoke.py
• backend/tools/tools.py
The callable tool(s) that hit RestCountries API (HTTP client logic).
• backend/prompts/country_information_search_prompt.txt
Prompt template(s) for the agent.
• backend/llm/google_gemini_ai.py, backend/llm/azure_open_ai.py
Provider adapters; indicate a “pluggable LLM backend” component.
• backend/utils/utils.py
Common helpers (formatting, parsing, error handling, etc.).
Ops / packaging
• Dockerfile, .devcontainer/*, requirements.txt, .dockerignore
Streamlit Server (frontend/app.py)
UI + session chat history + streaming renderer
Agent Runtime (backend/agents/...)
ReAct agent “brain” (decides tool use vs. direct answer)
LangGraph Orchestration (backend/graph/...)
Graph nodes/edges, state transitions, streaming/invocation
Tool Layer (backend/tools/tools.py)
“Country search / country info fetch” tool
LLM Provider (external)
• Google Gemini (active)
• Azure OpenAI (optional alternate)
Prompt Store (backend/prompts/*.txt)
Treated as a dependency feeding the agent/graph
Config/Secrets (.env environment variables)
Keys, model selection; optionally LangSmith settings
(Optional) LangSmith Tracing (external)
Only if LANGSMITH_TRACING=true
User → Streamlit UI
• message input event
Streamlit UI → Graph Invoke (backend/graph/invoke.py)
• passes user message + session history
Graph Invoke → LangGraph (backend/graph/graph.py)
• initializes state (from backend/graph/state.py)
LangGraph → Agent (backend/agents/country_information_agent.py)
• uses prompt(s)
Agent → LLM Adapter (backend/llm/google_gemini_ai.py or azure_open_ai.py) → LLM Provider
• “think/plan/act” step (ReAct)
Agent decides
• if tool needed: go to tool path (below)
• else answer directly
Agent → LLM Provider
• synthesizes final answer grounded in tool output
LangGraph → Streamlit UI
• stream tokens back
Streamlit UI → User
• renders streamed tokens; updates session chat history
Observability path (optional)
• LangGraph/Agent → LangSmith
• only if tracing enabled
ReAct + Tool-use
Call it out visually: “LLM decides to call tool” rather than “tool always called”.
• Use a decision diamond or a conditional edge: “Need external country data?”
Separation of concerns
Even though it’s one repo, the architecture is cleanly layered:
• Presentation: Streamlit UI
• Orchestration: LangGraph graph + state/invoke
• Domain agent: country_information_agent
• Integrations: tools (RestCountries), LLM adapters (Gemini/Azure)
• Configuration: env vars, model selection by import
Pluggable LLM backend
• GoogleGeminiLLM (default)
• AzureOpenAI (swap by import / config)
Streaming UX
That responses are streamed from backend to UI. This often gets missed; but it’s a key feature.
What to include from deployment (optional but useful)
• Docker container running streamlit run frontend/app.py
• environment variables from .env
• exposed port 8501
• external network egress to RestCountries + LLM provider (+ LangSmith)
This clarifies runtime boundaries and security considerations (keys never in code).
• Actor: User
• Container: Streamlit App (frontend/app.py)
• Component: Graph Invoke (backend/graph/invoke.py)
• Component: LangGraph Graph (backend/graph/graph.py)
• Component: Graph State (backend/graph/state.py)
• Component: CountryInformationAgent (backend/agents/country_information_agent.py)
• Component: Prompt Template (backend/prompts/country_information_search_prompt.txt)
• Component: Country Info Tool (backend/tools/tools.py)
• Component: LLM Adapter Interface (backend/llm/__init__.py)
• Impl: Google Gemini (backend/llm/google_gemini_ai.py)
• Impl: Azure OpenAI (backend/llm/azure_open_ai.py)
• External: RestCountries API
• External: Google Gemini API / Azure OpenAI API
• External (optional): LangSmith
• Config: .env (GOOGLE_GEMINI_KEY, model, LANGSMITH_*)