Overview & Architecture
Adeloop Agent API: Overview & Architecture
Adeloop allows you to publish selected semantic domains as governed APIs. This empowers external AI agents and applications—such as ChatGPT, Claude, Cursor, n8n, Zapier, or your custom backends—to safely and efficiently access your data.
Platform Flow
Integrating an agent with Adeloop follows a simple lifecycle:
- Connect Data: Link your warehouse, database, sheet, or file sources.
- Define Semantics: Convert source tables into a governed semantic domain.
- Publish: Navigate to
/hr/consoleand select the semantic domains to publish. - Generate Key: Create an Agent API and copy the generated API key.
- Integrate: Use the key in your external AI agents or applications.
How Execution Works
Adeloop is designed to do the heavy lifting safely. External AI clients should not calculate answers from raw tables or raw semantic metadata. Instead, they call Adeloop tools, and Adeloop orchestrates the execution.
The Power of "SQL Pushdown"
The default execution engine for business questions is Semantic SQL Pushdown. Adeloop does not pull millions of rows into a Python sandbox.
For example, if a semantic metric is defined as Total Revenue = SUM(orders.amount), Adeloop compiles a bounded aggregation:
SELECT country, SUM(amount) AS total_revenue
FROM orders
GROUP BY country
ORDER BY total_revenue DESC
LIMIT 100This ensures that:
- Compute happens close to the data inside your connected warehouse/database.
- Only tiny, aggregated result sets leave the source.
- AI agents receive fast JSON answers without needing raw database access.
Engine Strategy Recommendations
We recommend using the appropriate engine for the specific request type.
| Request Type | Execution Engine | Why |
|---|---|---|
| KPIs & Grouped Metrics | Source SQL Pushdown | Fast, accurate, highly scalable. |
| Cross-Source Joins | Federation Planner + DuckDB | Scales better than pulling raw data. |
| Non-SQL Fallback | DuckDB over bounded fetch | Practical for sources like Sheets. |
| Advanced Stats/ML | Async Python/E2B Job | Leverages Python libraries on reduced data (Future Phase). |
[!NOTE] E2B/sandbox analysis is an advanced feature intended for later async analysis phases, not the fast JSON/query external API path.
Current vs Future Phases
Currently Supported (Phases 1 & 2)
- Published semantic domains with hashed API keys and scopes.
- Usage logs and basic rate limits.
- Governed JSON API: Safe metric querying and domain schema endpoints.
- Natural-Language Ask API: Converts questions to semantic plans and executes them.
- MCP & OpenAPI: Integration endpoints for Agent frameworks.
Future Scale Roadmap
- Phase 3: LLM-based Semantic Query Planner with strict JSON schema.
- Phase 4: Advanced Federation Layer for cross-source joins.
- Phase 5: Streamable MCP (SSE) and OAuth integration.
- Advanced: Async E2B python analysis jobs over reduced data.
Next: Learn about the available endpoints and how to integrate in API Endpoints & Integrations.