AI Orchestrator & Sub-Agents
Relevant source files
The following files were used as context for generating this wiki page:
The AI Orchestrator & Sub-Agents system in Poneglyph serves as a humanitarian intelligence analyst platform. It is designed to help NGO workers, researchers, and task forces extract actionable insights from internal humanitarian datasets and the broader web. The system utilizes a main Orchestrator that manages specialized tools and delegates complex tasks to a "Deep Research" sub-agent specialist.
The primary goal of the orchestrator is to serve users making high-stakes resource allocation decisions by providing professional, concise, and analytical findings based on multi-source data synthesis.
Sources: apps/server/src/agents/prompts/system.ts:1-7, apps/server/src/agents/prompts/system.ts:46-47
Architecture and Components
The intelligence system is structured around a central Orchestrator that interacts with the user and coordinates various search capabilities. It follows a modular tool-calling pattern where specific search functions are invoked based on the user's query requirements.
System Workflow
The following diagram illustrates the interaction between the user, the Poneglyph Orchestrator, and the underlying research tools.
The Orchestrator prefers calling searchDatabase and webSearch in parallel for comprehensive results, reserving deepResearch for synthesis or multi-step fact-checking.
Sources: apps/server/src/agents/prompts/system.ts:9-25, apps/server/src/agents/prompts/system.ts:42-43, apps/server/src/agents/tools/search-db.ts:25-30
Core Capabilities and Tools
The system exposes three primary capabilities through the Orchestrator, each backed by specific implementation logic or sub-agent specialists.
| Capability | Tool Name | Description | Source/Provider |
|---|---|---|---|
| Internal Search | searchDatabase | Searches curated NGO reports, datasets, and field documents using semantic similarity. | pgvector / Drizzle |
| Web Search | webSearch | Provides real-time up-to-date results for current events and policy updates. | Gemini |
| Deep Research | deepResearch | Multi-step investigation for synthesizing multiple sources or fact-checking. | Tavily Sub-Agent |
Sources: apps/server/src/agents/prompts/system.ts:9-25, apps/server/src/agents/tools/search-db.ts:25-30
Semantic Database Search (searchDatabase)
This tool implements RAG (Retrieval-Augmented Generation) using pgvector for cosine similarity searches against the datasets table. It returns dataset titles, summaries, file links, and metadata.
- Logic: Embeds the user query and runs similarity ranking.
- Enrichment: Automatically generates presigned S3 URLs for file access and fetches associated tags for the results.
- Ranking: Uses
1 - (embedding <=> query_embedding)to determine relevance.
Sources: apps/server/src/agents/tools/search-db.ts:21-70
Deep Research Sub-Agent
The Deep Research specialist is a distinct agent persona focused on thorough investigation. It is triggered when webSearch results are insufficient or the query is complex.
- Process: Searches topics using multiple angles, extracts content from URLs, and cross-references findings.
- Output Structure: Bulleted findings, source URLs, statistics, and a confidence level (High/Medium/Low) for each claim.
- Focus Areas: Refugee data, NGO reports, academic research, and conflict zone news.
Sources: apps/server/src/agents/prompts/deep-research.ts:1-19, apps/server/src/agents/prompts/system.ts:22-25
Data Flow: Internal Search Execution
The database search tool utilizes raw SQL to bypass type conflicts between hoisted Drizzle ORM versions in the AI SDK.
User Interface Integration
The agent system is integrated into the frontend through a dedicated Research Dashboard and an Agent Panel component.
Research Dashboard
The dashboard provides a conversational thread interface where users can view the agent's progress, including status logs such as "Explored 12 files, 4 searches" or "Processed screen recording". It supports the rendering of interactive charts and media walkthroughs generated by the agent.
Sources: apps/web/src/app/research/page.tsx:15-32
Agent Interaction Component
The AgentPanel component manages the real-time chat state and file uploads.
| Feature | Implementation | File Path |
|---|---|---|
| Message Handling | useState with user/agent roles | apps/web/src/components/research/agent-panel.tsx |
| File Analysis | Support for .csv, .json, .xlsx | apps/web/src/components/research/agent-panel.tsx |
| Drag & Drop | onDrop handler for datasets | apps/web/src/components/research/agent-panel.tsx |
Sources: apps/web/src/components/research/agent-panel.tsx:21-65
Implementation Details
Internal Search SQL Logic
The search tool retrieves both the dataset and its source information (e.g., CKAN, NGO upload) in a single join.
SELECT
d.id, d.title, d.description, d.summary,
d.s3_keys, d.file_types, d.source_url,
s.name AS source_name, s.source_type,
1 - (d.embedding <=> ${embeddingStr}::vector) AS similarity
FROM datasets d
INNER JOIN sources s ON d.source_id = s.id
WHERE d.embedding IS NOT NULL
ORDER BY similarity DESC
LIMIT 5
Sources: apps/server/src/agents/tools/search-db.ts:47-64
Response Requirements
The Orchestrator must adhere to strict formatting guidelines:
- Citations: Always use inline markdown links
[title](https://github.com/Itz-Agasta/Poneglyph/blob/09062990523f5b26bff9226d5fa6008e1c5a4974/url). - Sectioning: Dedicated "Internal Datasets" and "Web Sources" sections.
- Tone: Professional and analytical, catering to life-or-death resource allocation decisions.
Sources: apps/server/src/agents/prompts/system.ts:27-47