Research Query
POST /api/agents/research/query
Execute entity-aware research query with strategic insights.
Performs sophisticated research queries that understand entities and their relationships, providing contextual results with strategic analysis.
Process:
- Parse query to identify key entities and concepts
- Execute semantic search across configured scope
- Extract entities from results
- Generate strategic insights
- Return ranked results with analysis
Args: request: ResearchQueryRequest with query and search parameters.
Returns: ResearchQueryResponse with results, entities, and insights.
Raises: HTTPException 400: Invalid query or parameters. HTTPException 500: Lagan processing error. HTTPException 503: Lagan agent not available.
Example Request:
json POST /api/agents/discovery/research/query { "query": "artificial intelligence applications in medicine", "search_scope": "documents", "max_results": 10, "include_entities": true, "include_insights": true, "context": {"project": "medical_ai"} }
Example Response:
json { "success": true, "query": "artificial intelligence applications in medicine", "total_results": 10, "results": [...], "entities": [...], "insights": ["AI medical applications show..."], "processing_time_ms": 523 }
Request Body required
Section titled “Request Body required ”Request for entity-aware research query.
Initiates a research query with entity extraction, strategic insights, and configurable search scope across documents and web sources.
Fields:
query: Research query or question (required, non-empty)search_scope: Scope of search (documents, web, all)max_results: Maximum number of results to return (1-100, default 10)include_entities: Whether to extract entities from resultsinclude_insights: Whether to generate strategic insightscontext: Additional context for query (project, domain, etc.)
Search Scope:
documents: Search only local document collectionsweb: Search web sources onlyall: Search both documents and web sources
Usage: Used to initiate research queries with intelligent result processing.
Integration:
- ResearchRoutes: Request validation for /research/query endpoint
- LaganAgent: Research query execution
- RAG System: Document retrieval
object
Research query or question
Scope of search (documents, web, all)
Maximum number of results to return
Extract and return entities from results
Generate strategic insights from results
Additional context (project, domain, etc.)
object
Responses
Section titled “ Responses ”Successful Response
Response for research query with results and insights.
Provides comprehensive research results with extracted entities, strategic insights, and performance metrics.
Fields:
success: Whether query was successfulquery: Original query texttotal_results: Total number of results foundresults: List of research results ordered by relevanceentities: Aggregated entities extracted from all resultsinsights: Strategic insights derived from resultsprocessing_time_ms: Total processing time in milliseconds
Usage: Returned by research endpoints after query execution.
Integration:
- ResearchRoutes: Response model for /research/query endpoint
- Frontend: Research results display and visualization
object
Whether query was successful
Original query
Total number of results found
Research results ordered by relevance
Single research result item.
Represents an individual result from a research query with content, source, relevance scoring, and extracted entities.
Fields:
title: Result title or headingcontent: Result content or excerptsource: Source URL or document IDrelevance_score: Relevance to query (0.0-1.0, higher is more relevant)entities: Entities extracted from this resultmetadata: Additional metadata (date, author, document type, etc.)
Usage: Used in research query responses to return individual results.
Integration:
- ResearchQueryResponse: Results list in research responses
- Frontend: Research results display
object
Result title or heading
Result content or excerpt
Source URL or document ID
Relevance to query
Entities found in result
Extracted entity from content with type classification and confidence scoring.
Represents a named entity (person, place, organization, concept, etc.) extracted from analyzed content with confidence scoring and contextual information.
Fields:
name: Entity name or identifier as extracted from contententity_type: Classification type (person, place, organization, concept, etc.)confidence: Extraction confidence score from 0.0 to 1.0context: Surrounding text context where entity was found
Usage: Used in perception and research responses to return extracted entities.
Integration:
- WebpagePerceptionResponse: Entity list in perception results
- ResearchResult: Entities extracted from research results
- EnrichContentResponse: Additional entities from enrichment
Additional metadata (date, author, etc.)
object
All entities extracted from results
Extracted entity from content with type classification and confidence scoring.
Represents a named entity (person, place, organization, concept, etc.) extracted from analyzed content with confidence scoring and contextual information.
Fields:
name: Entity name or identifier as extracted from contententity_type: Classification type (person, place, organization, concept, etc.)confidence: Extraction confidence score from 0.0 to 1.0context: Surrounding text context where entity was found
Usage: Used in perception and research responses to return extracted entities.
Integration:
- WebpagePerceptionResponse: Entity list in perception results
- ResearchResult: Entities extracted from research results
- EnrichContentResponse: Additional entities from enrichment
Strategic insights derived from results
Processing time in milliseconds
Validation Error