Agentic Search API¶

A modular, intelligent search orchestration API that combines traditional web search, web scraping, and AI-powered search to provide comprehensive answers to user queries.

Key Features¶

Multi-Provider Search — Brave, Google, Bing integration
Intelligent Routing — Automatic intent detection and agent selection
Relevance Filtering — AI-powered re-ranking and noise reduction
Result Deduplication — Smart cleaning of duplicate content sources
Web Scraping — URL content extraction with CSS selectors
AI Search — Perplexity AI integration for deep research
Referenced Summaries — LLM-generated answers with citations
OpenAI-Compatible — Drop-in replacement for chat completions

Quick Start¶

1. Clone & Install¶

git clone https://github.com/yourusername/agentic-search-engines.git
cd agentic-search-engines
pip install -r requirements.txt

2. Configure Environment¶

cp .env.example .env
# Edit .env with your API keys and configuration

Required environment variables: - LLM_MODEL — Fast reasoning model (e.g., openai/gpt-oss-20b) - LLM_SUMMARY_MODEL — Summary model (e.g., llama-3.3-70b-versatile)

3. Run Server¶

python api.py

Server runs at http://localhost:8000

API Endpoints¶

POST /v1/search¶

Main search endpoint with multiple flow types.

curl -X POST http://localhost:8000/v1/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the capital of France?",
    "flow": "agentic",
    "params": {
      "use_search": true,
      "providers": ["brave", "google"]
    }
  }'

Flow Types: | Flow | Description | |------|-------------| | agentic | Full orchestration (search + scrape + AI) | | search_only | Traditional web search | | scrap_only | URL content extraction | | ai_search_only | Perplexity AI search |

POST /v1/chat/completions¶

OpenAI-compatible chat endpoint with intelligent intent routing.

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agentic-search",
    "messages": [
      {"role": "user", "content": "Show me videos about machine learning"}
    ]
  }'

Automatic Intent Detection: - "extract text from https://..." → Web scraping - "show me videos about..." → Video search - "find pictures of..." → Image search - "latest news about..." → News search - General questions → Web search + AI summary

GET /health¶

Health check endpoint (no auth required).

Architecture¶

┌─────────────────────────────────────────────────────┐
│               API Layer (FastAPI)                   │
│  /v1/search          /v1/chat/completions           │
└──────────────────────┬──────────────────────────────┘
                       │
         ┌─────────────┴─────────────┐
         ▼                           ▼
┌──────────────────┐      ┌──────────────────────┐
│   Orchestrator   │      │  Intent Router Agent │
└────────┬─────────┘      └──────────┬───────────┘
         │                           │
         ▼                           ▼
┌─────────────────────────────────────────────────────┐
│              Specialized Agents                     │
│  SearchAgent │ ScrapAgent │ PerplexityAgent        │
│  QueryClassifier │ SearchFilter │ LLMClient        │
└─────────────────────────────────────────────────────┘

Core Agents¶

Agent	Purpose
OrchestrationAgent	Coordinates multi-step workflows
IntentRouterAgent	Detects intent for chat endpoint
SearchAgent	Executes web searches
ScrapAgent	Extracts content from URLs
PerplexityAgent	AI-powered search
LLMClientAgent	Generates summaries

Supporting Agents¶

Agent	Purpose
QueryClassifierAgent	Analyzes intent and language
SearchResultFilterAgent	AI-based result ranking
SearchQueryBuilderAgent	Optimizes search queries
TimeFreshnessAgent	Evaluates content recency

Configuration¶

Environment Variables¶

Variable	Description
`LLM_MODEL`	Fast reasoning model
`LLM_SUMMARY_MODEL`	Summary generation model
`LLM_PERPLEXITY_MODEL`	Perplexity model (default: `sonar`)
`TRAYLINX_BASE_URL`	LLM proxy base URL
`API_BASE_URL`	Main API base URL
`AUTH_SERVICE_URL`	Authentication service URL

Model Priority¶

1. Request-level model parameter
2. Environment variable (LLM_MODEL / LLM_SUMMARY_MODEL)
3. Error if neither set

Authentication¶

This API supports two authentication methods:

Option 1: User Authentication (Human API)¶

For human users accessing via UI or apps:

curl -X POST "http://localhost:8000/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user_token>" \
  -d '{"query": "AI news"}'

Header	Value	Description
`Authorization`	`Bearer <token>`	User token validated against Auth Service

Option 2: Agent Authentication (A2A / Machine-to-Machine)¶

For other agents or services calling this API:

curl -X POST "http://localhost:8000/search" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Secret-Token: <agent_token>" \
  -H "X-Agent-User-Id: <agent_id>" \
  -d '{"query": "AI news"}'

Header	Value	Description
`X-Agent-Secret-Token`	Agent's secret token	Obtained from Traylinx Sentinel
`X-Agent-User-Id`	Agent's UUID	Agent identifier registered with Sentinel

Authentication Flow¶

Request arrives
    │
    ├─ Has X-Agent-Secret-Token? ──→ AGENT MODE (validate via Sentinel)
    │
    └─ Has Authorization: Bearer? ─→ USER MODE (validate via Auth Service)

Note: Agent authentication headers take precedence over Bearer token if both are provided.

Documentation¶

📖 Full API Reference: docs/api_documentation.md

Includes: - Complete endpoint documentation - All request parameters - Response format reference - Error handling guide - Architecture details - Curl examples for all flows

Project Structure¶

├── agents/                    # Agent implementations
│   ├── orchestrator/         # Core orchestration
│   ├── search_agent.py       # Web search
│   ├── scrap_agent.py        # Web scraping
│   ├── perplexity_agent.py   # AI search
│   ├── intent_router_agent.py# Intent detection
│   ├── query_classifier_agent.py
│   ├── search_result_filter_agent.py
│   ├── llm_client_agent.py   # LLM integration
│   └── ...
├── services/                 # Service layer
│   ├── routes/              # API route handlers
│   └── utils/               # Utility functions
├── models/                   # Pydantic models
├── middleware/               # Auth middleware
├── config/                   # Configuration
├── docs/                     # Documentation
├── tests/                    # Test files
├── api.py                    # Main FastAPI app
└── requirements.txt

Testing¶

pytest tests/ -v

License¶

MIT License