Skip to main content

🤖 AI Agent Tools - Function Calling

Overview​

Vartovii now includes Function Calling integration with Gemini 3 preview (with Gemini 2.5 fallback), enabling the AI assistant to fetch real database data instead of generic responses.

Доступні Tools​

1. search_company​

Пошук компанії в базі даних.

Параметри:

  • company_name (required) - Назва компанії
  • country (optional) - Код країни (de, at, ch)

Приклад:

User: "Знайди компанію BMW"
→ Tool call: search_company({"company_name": "BMW"})
→ Response: Trust Score 71, 5621 відгуків, рейтинг 3.97

2. get_trust_score​

Детальний Trust Score з breakdown.

Параметри:

  • company_name (required) - Назва компанії

Response:

{
  "company_name": "BMW",
  "trust_score": 71,
  "risk_level": "MEDIUM",
  "breakdown": {
    "rating_quality": 23.8,
    "sentiment": 12.5,
    "volume": 20,
    "consistency": 10,
    "recency": 5
  }
}

3. list_companies​

Список топ роботодавців.

Параметри:

  • country (optional) - Фільтр по країні
  • limit (optional, default: 10) - Кількість компаній
  • sort_by (optional) - trust_score, review_count, avg_rating

Приклад:

User: "Покажи топ 5 компаній"
→ Tool call: list_companies({"limit": 5})
→ Response: SAP, BMW, Bosch, Lidl, Amazon

4. compare_companies​

Порівняння двох роботодавців.

Параметри:

  • company1 (required) - Перша компанія
  • company2 (required) - Друга компанія

Приклад:

User: "Порівняй BMW та Audi"
→ Tool call: compare_companies({"company1": "BMW", "company2": "Audi"})
→ Response: BMW wins (71 vs 57)

5. run_analysis 🚀​

Запуск збору та аналізу даних для НОВОЇ компанії (Magic Search).

Параметри:

  • company_name (required) - Назва компанії
  • country (optional, default: "de") - Код країни

Логіка:

  1. Шукає компанію на Kununu
  2. Створює scraping jobs (Kununu, Google, Reddit, Vacancies)
  3. Повертає job IDs для tracking

Приклад:

User: "Проаналізуй компанію Spotify"
→ Tool call: search_company({"company_name": "Spotify"}) → not found
→ Tool call: run_analysis({"company_name": "Spotify"})
→ Response: "🚀 Аналіз запущено! 4 jobs створено. Результат за 5-10 хв."

6. get_company_reviews 💬 NEW​

Показує sample відгуки працівників про компанію.

Параметри:

  • company_name (required) - Назва компанії
  • sentiment (optional) - positive, negative, all (default: all)
  • limit (optional) - Кількість відгуків (default: 5, max: 10)

Приклад:

User: "Покажи відгуки про BMW"
→ Tool call: get_company_reviews({"company_name": "BMW"})
→ Response: 5 reviews з ratings та джерелами

Response:

{
  "company_name": "BMW",
  "reviews": [
    {
      "text": "👍 Great work-life balance...",
      "rating": 4.5,
      "sentiment": "POSITIVE",
      "source": "kununu"
    }
  ],
  "summary": {
    "total": 5,
    "positive": 3,
    "negative": 2
  }
}

🍕 Pizza Tracker​

Візуалізація статусу AI Agent в реальному часі:

┌─────────────────────────────────────────┐
│  🤔 ─────── 🔍 ─────── 📊 ─────── ✍️   │
│ Думаю   Шукаю дані  Аналізую   Готую   │
│                                         │
│  🏢 Шукаю компанію...                   │
│  📊 Аналізую Trust Score...             │
└─────────────────────────────────────────┘

Steps:

  1. 🤔 Думаю... - AI обробляє запит
  2. 🔍 Шукаю дані... - Пошук в базі
  3. 📊 Аналізую... - Виконання tools
  4. ✍️ Готую відповідь... - Формування

🔐 API Security​

Agent Endpoints (Secured)​

Всі /api/agent/* endpoints захищені API Key:

# Without key - 401
curl https://sentryanalytic.com/api/agent/search-company

# With key - 200 OK
curl -H "X-API-Key: YOUR_KEY" \
  https://sentryanalytic.com/api/agent/search-company \
  -d '{"company_name": "BMW"}'

Config:

  • AGENT_API_KEY - зберігається в Secret Manager
  • Health check /api/agent/health - public (no auth)

Technical Implementation​

Architecture​

User Message → ChatWidget → /api/ai/chat
                               ↓
                    _should_use_tools() detection
                               ↓
                    Gemini 3 preview + FunctionDeclarations
                               ↓
                    _execute_tool_call_sync()
                               ↓
                    Direct DB Query / SmartSearchService
                               ↓
                    Final Response with Real Data

Key Files​

  • backend/ai/services/chat_service.py - Function Calling logic (6 tools)
  • backend/api/agent_tools.py - Standalone API endpoints + security
  • backend/services/smart_search.py - Magic Search service
  • dashboard_app/src/components/ChatWidget.jsx - Pizza Tracker UI

Completed Tools ✅​

  • search_company - Search company in database
  • get_trust_score - Detailed Trust Score breakdown
  • list_companies - Top employers ranking
  • compare_companies - Compare two employers
  • run_analysis - Start Magic Search for new companies
  • get_company_reviews - Sample reviews from company

Future Tools (Planned)​

  • get_industry_stats - Industry comparison statistics
  • track_analysis - Check status of running analysis
  • get_job_openings - Current vacancies from Indeed