Content
# VisaPros: Your AI-Powered Global Mobility Assistant
## 🚀 The Pitch
### The Problem
Navigating the complex web of global visa requirements is a daunting task, whether you're planning a holiday, a business trip, seeking medical treatment, pursuing higher education, or looking to relocate permanently. Applicants often find themselves overwhelmed by fragmented information, confusing legalese, and the sheer volume of documents required for different countries and visa types. Manually checking eligibility for multiple destinations is time-consuming and prone to error, leading to missed opportunities and application rejections.
### The Solution
**VisaPros** is an advanced Agentic AI system designed to act as your personal, intelligent visa receptionist. It leverages a parallel multi-agent architecture to simultaneously evaluate your eligibility for six major destinations (UK, Canada, US, Australia, Norway, Germany) across **any visa category**—Tourism, Business, Study, Healthcare, or Work. By parsing your documents once and cross-referencing them against real-time immigration rules, VisaPros provides a comprehensive, comparative roadmap for your global mobility.
### The Value
* **Universal Coverage:** Supports all visa types—from short-term tourist stays to long-term permanent residency.
* **Efficiency:** Instantly assesses eligibility for 6 countries in parallel, saving hours of manual research.
* **Strategic Insight:** Identifies "low-hanging fruit" – countries where you are closest to eligibility – and provides a prioritized list of missing documents that unlock the most opportunities.
* **Accuracy:** Uses specialized sub-agents equipped with Google Search to fetch the latest, authoritative immigration rules, ensuring advice is never outdated.
---
## 📝 Write Up
### Project Journey
The development of VisaPros began with the goal of simplifying the initial triage phase of travel and migration planning. We started with a single agent but quickly realized that a linear approach was too slow for multi-country evaluation. We evolved the architecture to use the **Agent-to-Agent (A2A)** framework, deploying specialized "Country Agents" as independent microservices. This allowed for true parallel execution and modular scalability.
We faced challenges in coordinating these independent agents and aggregating their results meaningfully. The breakthrough came with the implementation of a **Hybrid Workflow**:
1. **Sequential Parsing:** To ensure accuracy.
2. **Parallel Evaluation:** To ensure speed.
3. **Strategic Advising:** To provide value-added synthesis.
### Architecture
VisaPros employs a **Hub-and-Spoke** architecture enhanced with **Parallel Processing**:
1. **Receptionist Agent (Hub):** The main interface that orchestrates the workflow. It uses a `SequentialAgent` pattern to manage the pipeline.
2. **Parsing Agent:** A specialized `LlmAgent` that extracts structured data (JSON) from user documents.
3. **Parallel Evaluator:** A `ParallelAgent` that triggers six remote `RemoteA2aAgent` instances simultaneously.
4. **Country Agents (Spokes):** Independent FastAPI servers running `LlmAgent` instances for each country. They use **Google Search** to validate requirements against current laws.
5. **Strategic Advisor:** An aggregation agent that analyzes the collective results to rank countries and recommend the "best path" based on document completeness.
```mermaid
graph TD
User[User] -->|Documents/Query| VisaPros[VisaPros Receptionist]
subgraph "Sequential Workflow"
VisaPros --> Parsing[Parsing Agent]
Parsing -->|Parsed Info| Parallel[Parallel Evaluator]
subgraph "Parallel Execution (A2A)"
Parallel -->|A2A Call| UK[UK Agent]
Parallel -->|A2A Call| CA[Canada Agent]
Parallel -->|A2A Call| US[US Agent]
Parallel -->|A2A Call| AU[Australia Agent]
Parallel -->|A2A Call| NO[Norway Agent]
Parallel -->|A2A Call| DE[Germany Agent]
end
UK & CA & US & AU & NO & DE -->|Checklists| Advisor[Strategic Advisor]
end
Advisor -->|Ranked Roadmap| VisaPros
VisaPros -->|Final Response| User
```
---
## 🤖 How Gemini is Being Used
VisaPros is powered entirely by **Google Gemini 2.5 Flash Lite**, chosen for its speed, cost-efficiency, and strong reasoning capabilities.
* **Document Understanding:** The `parsing_agent` uses Gemini's context window to ingest messy, unstructured text (simulating OCR'd documents) and output clean, structured JSON.
* **Complex Reasoning:** The `strategic_advisor` uses Gemini to perform multi-variable optimization – finding the subset of missing documents that maximizes the user's "mobility score" across all target countries.
* **Tool Use:** Each country agent leverages Gemini's function calling capabilities to autonomously query **Google Search**, verifying specific visa rules (e.g., "UK Tourist Visa financial requirements 2025") in real-time.
---
## 🛠️ Setup & Instructions
### Prerequisites
* Python 3.10+
* Google Cloud Project with Vertex AI API enabled (or AI Studio API Key)
* `google-adk` installed
### Installation
1. **Clone the repository:**
```bash
git clone <repo-url>
cd VisaPros
```
2. **Install dependencies:**
```bash
pip install -r requirements.txt
```
3. **Configure Environment:**
Create a `.env` file in the root directory:
```env
GOOGLE_API_KEY=your_api_key_here
GOOGLE_GENAI_USE_VERTEXAI=0 # Set to 1 if using Vertex AI
```
### Running the System
1. **Start the Country Agent Servers:**
These agents run as independent microservices. Use the helper script to start them all:
```bash
./start_servers.sh
```
*Wait for the message "✅ All country agent servers started!"*
2. **Run the Main Agent:**
In a new terminal window, run the receptionist agent:
```bash
adk run visaPros
```
3. **Interact:**
* **Scenario 1 (Strategic):** "I want to travel for a summer vacation. Here are my documents... Where is easiest to get a tourist visa?"
* **Scenario 2 (Specific):** "Can I apply for a Student Visa in Canada?"
### Stopping the System
To stop all running agent servers and clean up processes:
```bash
pkill -f 'uvicorn.*Agent.server'
```
### Troubleshooting
* **Port Conflicts:** Ensure ports 8001-8006 are free.
* **API Key:** Verify your `GOOGLE_API_KEY` is valid and has access to Gemini models.
