agenticX — Comprehensive Architecture & Implementation Review

1 Architectural Decision

We evaluated four deployment patterns and selected Cloudflare-first with AI Gateway as the production architecture.

Option	Runtime	AI Models	Cost	Complexity
B. CF Workers + AI Gateway	TS at edge	All via Gateway	Free tier + tokens	Low
A. GCP Cloud Run + ADK	Python on GCP	Gemini + LiteLLM	Cloud Run + Vertex	High
C. Hybrid (CF + GCP)	Both	Split by task	Both platforms	Highest
D. Workers AI only	TS at edge	Llama/Mistral only	Neurons only	Low but limited

Why Cloudflare-First

Single platform — compute, state, AI, CDN, DNS in one
AI Gateway is the multiplexer — one endpoint routes to 24+ providers
Edge-first — Workers AI for fast tasks, Gateway for reasoning
Existing code is TypeScript — no rewrite needed
Free tier is generous — 100K req/day, 5M D1 reads, caching free

GCP Remains as Stubs

Python ADK scaffolding preserved as reference patterns
Google Workspace APIs called via REST fetch() from Workers
Cloud Run available for future heavy compute if needed
Vertex AI accessible via AI Gateway (no direct GCP auth required)
agenticx-agents repo stays as architecture docs + Python reference

2 System Architecture

AX demo-dev.agilex.co.za — Cloudflare Worker

API Router/api/agents/*
/api/candidates/*
/.well-known/agent.json

Agent DispatcherOrchestrator routes
to 5 sub-agents

D1 DatabaseCandidates, vacancies
Activity, documents

KV StoreSessions, cache
Rate limits, locks

Static AssetsPortal UI
Guides

AI AI Gateway — Multi-Model Inference

Workers AILlama 3.1 8B (edge)
BGE embeddings
Zero cold start

Gemini 2.5 FlashCV parsing (JSON)
Reports, email drafts
via Google AI Studio

Gemini 2.5 ProCandidate scoring
Complex reasoning
via Google AI Studio

Claude SonnetOffer letters
Quality writing
via Anthropic API

Fallback ChainGemini → Claude
→ Workers AI
Automatic

REST fetch() — Google APIs

GW Google Workspace — Content & Documents (stubs ready for real APIs)

Google DriveCV upload, folders
Share, list files

GmailSend, draft
Search, read

CalendarEvents + Meet
FreeBusy, cancel

SheetsPipeline tracker
Append, read

AuthService account
JWT + delegation

3 A.G.I.L.E. Agents

Ava

Acquire

Gemini Flash / Edge

Grant

Gauge

Gemini Pro

Iris

Integrate

Gemini Flash

Leo

Leverage

Gemini Flash

Elle

Engage

Claude Sonnet

Agent Capabilities

Agent	Actions	Tools Used	Status
Acquire	`parse-cv`, `search`	Workers AI, Drive, Sheets, ATS	Working
Gauge	`score`, `bulk-score`	Gemini Pro, ATS, Sheets	Working
Integrate	`schedule`	Calendar, Gmail, ATS	Stub tools
Leverage	`report`, `dashboard`	Sheets, ATS, Drive	Working
Engage	`notify` (stage-update, rejection, offer, teams)	Claude, Gmail	Stub tools

Orchestrator Flow

CV Received

Acquire
Parse + Store

Gauge
Score 0-100

Integrate
Schedule

Engage
Notify

Gauge auto-advances to Integrate if score ≥ 80. Engage fires after each stage transition.

4 AI Model Routing via AI Gateway

All inference through one OpenAI-compatible endpoint: gateway.ai.cloudflare.com/v1/{account}/{gateway}/compat/chat/completions

Task	Model	Provider	Why	Fallback
CV text → JSON	`workers-ai/llama-3.1-8b`	Edge	Fast, free, structured	Gemini Flash
CV structured parse	`google/gemini-2.5-flash`	Google	Good JSON output, cheap	Workers AI
Candidate scoring	`google/gemini-2.5-pro`	Google	Strong reasoning	Claude Sonnet
Offer letters	`anthropic/claude-sonnet-4-6`	Anthropic	Quality writing, legal	Gemini Pro
Rejection feedback	`anthropic/claude-sonnet-4-6`	Anthropic	Empathetic tone	Gemini Flash
Pipeline reports	`google/gemini-2.5-flash`	Google	Data synthesis, fast	Workers AI 70B
Routine emails	`workers-ai/llama-3.1-8b`	Edge	Volume, templated, free	Gemini Flash
Embeddings	`workers-ai/bge-base`	Edge	Always edge, instant	—

AI Gateway Features

Semantic Caching

Identical queries return cached results instantly. TTL: 1h parsing, 24h reports. Expect 30-50% hit rate after 3 months.

Cost Tracking

cf-aig-metadata header tags every request with agent name, task type, and vacancy ID. Dashboard shows cost per agent.

Fallback Routing

If Gemini is down, Claude handles scoring. If both fail, Workers AI provides degraded but functional response.

Calling Pattern

// Edge AI (free, instant)
const result = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages, max_tokens });

// AI Gateway → Gemini or Claude (same endpoint, different model string)
const resp = await fetch(`https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/compat/chat/completions`, {
  method: 'POST',
  headers: {
    'cf-aig-authorization': `Bearer ${aigToken}`,
    'cf-aig-metadata': JSON.stringify({ agent: 'gauge', task: 'score' }),
  },
  body: JSON.stringify({ model: 'google/gemini-2.5-pro', messages, max_tokens: 500 }),
});

5 Google Workspace Integration

All Google APIs are standard REST, called via fetch() from Cloudflare Workers. No Python SDK needed. Currently stubbed — returns simulated responses when service account key is not configured.

Service	Functions	Agent	Status
Drive	`uploadFile`, `createFolder`, `listFiles`, `shareFile`	Acquire	Stub
Gmail	`sendEmail`, `createDraft`, `searchEmails`	Engage	Stub
Calendar	`createEvent` (+ Meet), `findFreeSlots`, `listEvents`	Integrate	Stub
Sheets	`appendRow`, `readRange`, `updateCell`	Leverage	Stub
Auth	Service account JWT → access token (cached in KV)	All	Stub

To Activate Google Workspace

Create GCP project, enable Gmail/Calendar/Drive/Sheets APIs
Create service account with domain-wide delegation
Base64-encode the service account JSON key
wrangler secret put GOOGLE_SA_KEY (paste base64 value)
Set GOOGLE_DELEGATED_USER, folder IDs, sheet ID, calendar ID in wrangler.toml
Deploy — stubs automatically switch to real API calls

6 A2A Agent Discovery

The portal serves an A2A agent card at /.well-known/agent.json advertising 5 recruitment skills. Any A2A-compatible system can discover and interact with agenticX agents.

{
  "name": "agenticX",
  "url": "https://demo-dev.agilex.co.za",
  "skills": [
    { "id": "recruit/parse-cv", "agent": "acquire" },
    { "id": "recruit/score", "agent": "gauge" },
    { "id": "recruit/schedule", "agent": "integrate" },
    { "id": "recruit/report", "agent": "leverage" },
    { "id": "recruit/notify", "agent": "engage" }
  ],
  "authentication": { "schemes": ["bearer"] }
}

7 Codebase Inventory

Repo	Language	Files	LOC	Purpose	Deployed
agilex-portal	TypeScript	14	1,485	Cloudflare Worker — agents, AI Gateway, D1, portal UI	agilex-app.pages.dev
agenticx-agents	Python	38	2,092	Google ADK reference + architecture docs (GCP stubs)	Reference
agilex-site	Astro/TS	5	513	Marketing site — agilex.co.za	agilex-site.pages.dev

Key Portal Source Files

File	LOC	Purpose
`src/agents/router.ts`	378	All 5 A.G.I.L.E. agents — dispatch, tools, Edge AI calls
`src/lib/ai-gateway.ts`	208	Multi-model inference — Workers AI + Gemini + Claude via AI Gateway
`src/index.ts`	126	Worker entry — router, CORS, A2A card, Env types
`src/sim/m365.ts`	212	Legacy M365 simulation (to be replaced by Google stubs)
`src/lib/google/*.ts`	239	Google Workspace stubs — auth, Drive, Gmail, Calendar, Sheets
`src/api/ai.ts`	88	Raw AI inference + embedding endpoints
`src/api/candidates.ts`	52	Candidate CRUD (D1)
`src/api/seed.ts`	94	Demo data — 10 clients, 8 vacancies, 15 candidates
`schema.sql`	86	D1 schema — 6 tables

8 Implementation Status

Working Now

5 agent endpoints with real logic (D1 + Workers AI)
AI Gateway client with model routing table + fallback chain
D1 database — candidates, vacancies, clients, activity, AI usage
A2A agent card at /.well-known/agent.json
CV parsing with Edge AI (Llama 3.1 8B — tested on Cloudflare)
Candidate scoring with reasoning (Edge AI)
Pipeline report generation from D1 data
Demo data seeder (15 candidates, 8 vacancies, 10 clients)
Portal UI with 6 tabs (dashboard, agents, pipeline, M365, Huly, Edge AI)
Marketing site with homepage + contact page

Stubbed — Ready for Real Implementation

Google Drive upload / folder / share / list
Gmail send / draft / search
Google Calendar events / FreeBusy / Meet links
Google Sheets append / read / update
Google auth (JWT service account → token exchange)
AI Gateway connection (needs CF_AIG_TOKEN secret)
Gemini inference (needs GOOGLE_AI_KEY secret)
Claude inference (needs ANTHROPIC_API_KEY secret)
demo-dev.agilex.co.za DNS routing

Activation Sequence

Each stubbed capability activates by setting one secret or env var — no code changes needed:

#	Capability	Set This	Activates
1	AI Gateway → Gemini	`wrangler secret put GOOGLE_AI_KEY`	CV parsing via Gemini Flash, scoring via Gemini Pro
2	AI Gateway → Claude	`wrangler secret put ANTHROPIC_API_KEY`	Offer letters, rejections via Claude Sonnet
3	AI Gateway auth	`wrangler secret put CF_AIG_TOKEN`	All Gateway routing, caching, cost tracking
4	Google Workspace	`wrangler secret put GOOGLE_SA_KEY`	Drive, Gmail, Calendar, Sheets — all tools go live
5	Custom domain	DNS AAAA `demo-dev` on `agilex.co.za`	Portal accessible at `demo-dev.agilex.co.za`

9 Test Cases

Edge AI (no API keys needed)

CV parse via Workers AI

POST /api/agents/acquire/parse-cv with CV text → structured JSON with name, skills, etc.

Pass

Embedding generation

POST /api/ai/embed with text → 768-dim vector preview

Pass

Candidate scoring (edge fallback)

POST /api/agents/gauge/score with candidateId → score 0-100

Pass

Model listing

GET /api/ai/models → edge + gateway models

Pass

AI Gateway → Gemini (needs GOOGLE_AI_KEY)

Gemini Flash CV parse

POST /api/ai/infer with model=google/gemini-2.5-flash → structured candidate JSON

Key needed

Gemini Pro scoring

POST /api/agents/gauge/score with Gemini Pro model → score + reasoning + tier

Key needed

Gemini report generation

POST /api/agents/leverage/report → pipeline narrative + metrics

Key needed

Semantic caching

Same request twice → second returns faster with cache hit header

Key needed

AI Gateway → Anthropic Claude (needs ANTHROPIC_API_KEY)

Claude offer letter

POST /api/agents/engage/notify type=offer → professional offer email in SA English

Key needed

Claude rejection with feedback

POST /api/agents/engage/notify type=rejection → constructive feedback

Key needed

Claude interview questions

Generate 5-8 structured questions for a vacancy + candidate

Key needed

Fallback Chain

Gemini down → Claude

Block Gemini in gateway → same output from Claude

Manual

All gateway down → Workers AI

Block all providers → Llama 8B handles task at edge

Manual

Google Workspace (needs GOOGLE_SA_KEY)

Upload CV to Drive

PDF bytes → file in Candidates/Active/{name}/ with Drive URL

SA key needed

Send email via Gmail

To, subject, body → email delivered from craig@agilex.co.za

SA key needed

Create calendar event

Summary, datetime, attendees → event with Google Meet link

SA key needed

Append to Sheets

Row values → new row in Pipeline Tracker

SA key needed

End-to-End Workflows

E2E1

Full CV intake

Upload PDF → parse → score → Drive upload → Sheets row → activity log

Phase 2

E2E2

Interview scheduling

Select candidate → find slots → book Calendar → send Gmail → update stage

Phase 2

E2E3

Pipeline report

Request → gather Sheets data → Gemini narrative → upload Drive PDF

Phase 2

E2E4

A2A discovery

GET /.well-known/agent.json → valid A2A card with 5 skills

Pass

POPIA Compliance

Consent tracking

Create candidate → consent_given timestamp in D1

Schema ready

No raw CV in DB

Parse CV → only structured fields + Drive URL stored in D1

Pass

Audit trail

Every agent action → activity logged with timestamp, agent, action

Pass

10 Cost Projection

Component	Monthly (ZAR)	Tier
Cloudflare (Workers, D1, KV, Pages, DNS, CDN)	R0	Free
AI Gateway (metering, caching, analytics)	R0	Free
Workers AI (Llama 8B + BGE embeddings)	~R90 – R180	Usage
Gemini API (Flash + Pro via AI Gateway)	~R180 – R540	Usage
Anthropic API (Claude Sonnet via AI Gateway)	~R360 – R720	Usage
Google Workspace	Existing	—
Total	R630 – R1,440	~$35–80/mo

11 Timeline & Next Steps

Phase	Scope	Effort	Status
Phase 0	Agent scaffold, AI Gateway client, Google stubs, A2A card, architecture doc	Done	Complete
Phase 1	Set API keys (Gemini, Claude, AI Gateway) → activate multi-model routing	1 hour	Next
Phase 2	Wire agents to use `ai-gateway.ts` infer() instead of direct Workers AI	2-3 days	Planned
Phase 3	Google Workspace — implement real auth + Drive + Gmail + Calendar + Sheets	1 week	Planned
Phase 4	E2E workflows — CV intake → score → schedule → notify	3-4 days	Planned
Phase 5	Deploy to `demo-dev.agilex.co.za`, POPIA audit, demo readiness	2 days	Planned

Immediate Next Action

Activate AI Gateway (1 hour)

Create AI Gateway in Cloudflare dashboard: AI → AI Gateway → Create → "agilex-agents"
Get a Google AI Studio API key from aistudio.google.com
Get an Anthropic API key from console.anthropic.com

Set secrets:

wrangler secret put CF_AIG_TOKEN
wrangler secret put GOOGLE_AI_KEY
wrangler secret put ANTHROPIC_API_KEY

Deploy: wrangler deploy

Test multi-model:

curl -X POST agilex-app.pages.dev/api/ai/infer \
  -d '{"model":"google/gemini-2.5-flash","prompt":"Hello from AgileX"}'

curl -X POST agilex-app.pages.dev/api/ai/infer \
  -d '{"model":"anthropic/claude-sonnet-4-6","prompt":"Hello from AgileX"}'