Realcolab is an autonomous AI Agent capable of performing deep research tasks. Built on the Cloudflare stack, it leverages durable execution workflows to plan research strategies, execute parallel data gathering, and generate comprehensive, cited answers from your private knowledge base.
- 🧠 Agentic Reasoning: Instead of blindly searching, the agent analyzes the user's request and creates a research plan with specific sub-queries.
- ⚡ Parallel Execution: Executes multiple vector search operations concurrently to gather diverse perspectives on a topic.
- 📝 Citation-Backed Answers: Every claim in the final output is strictly cited against source documents stored in the database.
- 🔄 High-Throughput Ingestion: dedicated pipeline using the Workers AI Batch API to embed and store large documents efficiently.
- 🛡️ Durable Orchestration: Uses Cloudflare Workflows to ensure long-running tasks (like massive ingestions or multi-step research) complete reliably, even if they exceed standard timeout limits.
The system runs on two primary pipelines orchestrated by a single AgentWorkflow class:
- Chunking: Intelligently splits raw text into semantic chunks using LangChain.
- Embedding: Generates vector embeddings in batches using
@cf/baai/bge-base-en-v1.5. - Persistence: Transactionally stores metadata in D1 (SQL) and vectors in Vectorize.
- Plan: Llama 3.3 70B decomposes the query into 1-3 targeted sub-queries.
- Gather: The agent executes these sub-queries in parallel against the Vectorize index, re-ranking results by relevance.
- Synthesize: Retrieval context is hydrated from D1, and the model generates a final report citing specific source IDs.
- Runtime: Cloudflare Workers
- Orchestration: Cloudflare Workflows
- Database: Cloudflare D1 (SQLite)
- Vector Database: Cloudflare Vectorize
- AI Models:
- Reasoning:
@cf/meta/llama-3.3-70b-instruct-fp8-fast - Embeddings:
@cf/baai/bge-base-en-v1.5
- Reasoning:
- Language: TypeScript
- Node.js & npm
- Cloudflare Wrangler CLI (
npm install -g wrangler) - A Cloudflare account with Workers AI enabled
git clone [https://github.com/ravarch/realcolab.git](https://github.com/ravarch/realcolab.git)
cd realcolab
npm install
Create the D1 database and Vectorize index. Ensure the names match your wrangler.jsonc.
# Create D1 Database
wrangler d1 create agent-db
# Create Vectorize Index (Dimensions: 768 for BGE-Base)
wrangler vectorize create agent-memory --dimensions=768 --metric=cosine
Note: Update wrangler.jsonc with the IDs generated from the commands above.
Initialize the schema for documents and chunks.
wrangler d1 migrations apply agent-db --local
# OR for production
wrangler d1 migrations apply agent-db --remote
wrangler deploy
The Agent exposes a REST API for interaction.
Uploads content to the knowledge base.
POST /api/ingest
{
"content": "Full text content of the document...",
"sourceUrl": "[https://example.com/article](https://example.com/article)",
"metadata": {
"author": "John Doe",
"category": "Science"
}
}
Response:
{ "id": "workflow-instance-id", "status": "queued" }
Triggers the autonomous research agent.
POST /api/research
{
"query": "What are the impacts of plastic pollution on marine life?"
}
Response:
{ "id": "workflow-instance-id", "status": "thinking" }
Poll this endpoint to retrieve the agent's progress and final answer.
GET /api/status?id=<workflow-instance-id>
Response (Success):
{
"status": "complete",
"output": {
"plan": {
"thoughtProcess": "To answer this, I need to look for...",
"subQueries": ["plastic ingestion statistics", "marine ecosystem impact"]
},
"answer": "Plastic pollution affects marine life by... [Source: ID_123]",
"sources": ["[https://example.com/article](https://example.com/article)"]
}
}
- Deterministic IDs: Document IDs are generated strictly within workflow steps to ensure replayability.
- Batching: Ingestion respects Workers AI batch limits (20 items/batch) to ensure stability.
- Type Safety: Fully typed event payloads and database responses.
This project is licensed under the MIT License.