AgileX — Agent Framework & Wiring Plan

Framework landscape, tooling decisions, integration matrix, and the path to a working E2E demo

Cloudflare WorkersAI GatewayMCP ProtocolA2A Discovery Gemini 2.5Claude SonnetWorkers AIHuly ATS Google Workspace7 Repos~14K LOC

1 Agent Framework Landscape

Seven frameworks evaluated against AgileX requirements: edge deployment, multi-model, MCP/A2A, South African context.

FrameworkLanguageModelsA2AMCPDeployBest ForAgileX Fit
Google ADKPy/TS/Go/JavaMulti (LiteLLM)NativeNativeCloud Run/GKE/VertexGCP teams, interop standardsReference
LangGraphPythonMultiVia LangChainYesAnyFull-control graph orchestrationOverhead
CrewAIPythonMultiNoLimitedAnyFast prototyping, role metaphorNo checkpoints
OpenAI Agents SDKPythonOpenAI onlyNoNoOpenAI CloudOpenAI-first teamsLocked
Anthropic Agent SDKPythonClaude onlyImpliedNativeAnthropic APIClaude-first, MCP-nativeFor quality tasks
AutoGen/AG2PythonMultiNoNoAnyResearch debate patternsNot mature
AgentForceConfigEinsteinNoNoSalesforce>60% Salesforce shopsVendor lock

Our Decision: Custom TypeScript on Cloudflare + Protocols

We don't adopt any single framework. Instead, we use Cloudflare Workers as the runtime, AI Gateway as the model multiplexer, A2A for agent discovery, and MCP for tool access. This gives us multi-model, edge-first, and protocol-compliant without framework lock-in.

Google ADK stays as a reference pattern (agenticx-agents repo). If we ever need GCP-native deployment, the ADK scaffolding is ready.

2 Protocols We Use

A2A (Agent-to-Agent)

Status: Implemented
What: JSON-RPC over HTTP. Agent card at /.well-known/agent.json.
Where: agilex-portal serves the card with 5 skills.
Why: Any A2A client can discover and call our agents.

MCP (Model Context Protocol)

Status: Implemented in huly-recruit-mcp
What: Tool/data protocol. MCP server exposes Huly tools.
Where: 3 tools: create_talent, create_vacancy, create_application.
Why: Claude Code, Cursor, any MCP client can call Huly directly.

Agent Skills

Status: Reference (2nth-skills repo)
What: SKILL.md with YAML frontmatter + scripts.
Where: biz/hr/recruitment/SKILL.md has the full value chain.
Why: Agents load skills contextually, not monolithically.

3 AI Model Strategy

Multi-model via Cloudflare AI Gateway. Each task routes to the best model. Automatic fallback chain.

TaskPrimaryProviderFallbackWhy This Model
CV text → JSONLlama 3.1 8BEdge (free)Gemini FlashFast structured extraction, zero cost
CV structured parseGemini 2.5 FlashGoogleWorkers AIGood JSON output, cheap
Candidate scoringGemini 2.5 ProGoogleClaude SonnetStrong reasoning for fair evaluation
Offer lettersClaude Sonnet 4.6AnthropicGemini ProQuality writing, legal precision
Rejection feedbackClaude Sonnet 4.6AnthropicGemini FlashEmpathetic, constructive tone
Pipeline reportsGemini 2.5 FlashGoogleWorkers AIData synthesis, fast
Routine emailsLlama 3.1 8BEdge (free)Gemini FlashHigh volume, templated
EmbeddingsBGE Base v1.5Edge—768-dim vectors, instant

Inference Platforms

PlatformRoleSA Advantage
Cloudflare Workers AIDefault edge inference (Llama, BGE)Global edge, free tier, no FX
Cloudflare AI GatewayProxy to Gemini, Claude, GPT, any providerCaching, cost tracking, fallback
OllamaLocal dev inference (POPIA, offline)No FX, load-shedding resilient
LiteLLMReference only (used by ADK in Python repo)Model-agnostic config switching

4 Integration Matrix — What's Real vs Stubbed

IntegrationStatusRepoEnv VarNotes
Workers AI (Llama 3.1 8B)Realagilex-portalAI bindingWorks on deployed Worker. Fallback locally.
AI Gateway (Gemini, Claude)Realagilex-portalCF_AIG_TOKEN + API keysNeeds secrets set. Falls back to Workers AI.
CV Parser (PDF/DOCX → JSON)Realagilex-toolsCV_PARSER_URLWorking. Needs deploy + env var.
Paton CV FormatterRealagilex-tools—Working. Multi-brand.
Huly create_talentRealhuly-recruit-mcpHULY_* varsWorking. Needs Huly instance.
Huly create_vacancyRealhuly-recruit-mcpHULY_* varsAuto-seeds 7 pipeline stages.
Huly create_applicationRealhuly-recruit-mcpHULY_* varsLinks talent → vacancy at stage.
D1 DatabaseRealagilex-portalDB binding6 tables, seeded.
A2A Agent CardRealagilex-portal—5 skills published.
Google DriveStubagilex-portalGOOGLE_SA_KEYReturns fake URLs. Needs service account.
GmailStubagilex-portalGOOGLE_SA_KEYTemplates defined. No real send.
Google CalendarStubagilex-portalGOOGLE_SA_KEYMock events. No real booking.
Google SheetsStubagilex-portalGOOGLE_SA_KEYMock rows. No real spreadsheet.
Key insight: The three hardest integrations (CV parsing, Huly ATS, multi-model AI) are all already working. The stubs are standard Google REST APIs — straightforward to implement once a service account is provisioned.

5 E2E Data Flow — CV to Huly Talent


Recruiter drops CV in simulator (agilex-sim)
  │
  ├─1─► POST /api/agents/acquire/parse-cv  (agilex-portal)
  │     ├── Try: agilex-tools/api/tools/cv-parser  (real PDF→JSON)
  │     ├── Fall back: Workers AI inline extraction
  │     └── Fall back: raw text passthrough
  │
  ├─2─► Gemini Pro scores candidate 0-100  (via AI Gateway)
  │     ├── Auto-advance to Screening if ≥80
  │     └── Fall back: Workers AI scoring
  │
  ├─3─► huly-recruit-mcp/create_talent  (real Huly ATS write)
  │     ├── Creates Person + Candidate mixin
  │     ├── Adds email/phone/LinkedIn channels
  │     └── Links Drive CV URL as Homepage channel
  │
  ├─4─► Google Drive upload  (STUB → real when service account ready)
  │     └── Store CV in /Candidates/Active/{name}/
  │
  ├─5─► Gmail notification  (STUB → real when service account ready)
  │     └── Send acknowledgement to candidate
  │
  └─6─► D1: INSERT candidate + LOG agent_activity

Steps 1-3 are real today. Steps 4-5 are stubs. Step 6 is real (D1).

6 Wiring Plan — What to Do and In What Order

#TaskEffortDependenciesResult
1Deploy agilex-tools to agilex-tools.pages.dev5 minNoneCV parser API goes live
2Set CV_PARSER_URL on portal + deploy10 minStep 1Acquire agent calls real parser
3Set AI Gateway secrets (CF_AIG_TOKEN, GOOGLE_AI_KEY, ANTHROPIC_API_KEY)15 minCreate AI Gateway in CF dashboardMulti-model scoring works
4Start Huly locally + run MCP seed script30 minDocker runningHuly workspace with demo data
5Wire portal → huly-recruit-mcp (HTTP wrapper)1-2 hrsStep 4Acquire agent creates real Huly talents
6Google Workspace service account1 hrGCP projectDrive, Gmail, Calendar, Sheets go live
7Update simulator to show real API responses30 minSteps 1-3Sim shows "Live" badges on real data
Steps 1-3 can be done in 30 minutes — they just need deploy + env vars. This gives a demo where: simulator → portal → real CV parse → real AI scoring. No Huly or Google needed yet.

7 Consolidated Repo Map

RepoOrgRoleLOCStatus
agilex-portal2nth-aiAPI gateway + agent orchestrator1,650Active
agilex-tools2nth-ai (mirror)CV parser + recruitment tools API3,646Active
huly-recruit-mcp2nth-ai (mirror)MCP server for Huly ATS1,149Active
agilex-sim2nth-aiRecruiter-first simulator UI657Active
agilex-site2nth-aiMarketing site (Astro)513Active
agilex-docs2nth-aiInternal documentation hub~4,000Active
agenticx-agents2nth-aiPython ADK reference + architecture2,092Reference

Total active codebase: ~7,615 LOC TypeScript/Astro + ~4,000 LOC documentation.

8 What Makes This Stack Different

No Framework Lock-in

We use protocols (A2A, MCP) not frameworks. Any A2A client can discover our agents. Any MCP client can call Huly. Models swap via one env var.

Edge-First

Agents run on Cloudflare Workers — 300+ cities, zero cold starts. CV parsing happens at the edge before hitting any external API. ~50ms for edge tasks vs ~200ms for cloud.

Real Tools Already Working

The CV parser extracts real PDFs. The MCP server writes real Huly records. The AI Gateway routes to real models. This isn't a demo — it's infrastructure with a demo UI on top.

Graceful Degradation

Every integration has a fallback: tools API → Workers AI → raw text. Gemini → Claude → Llama. Huly MCP → stub. Google → stub. The system always works, just at different fidelity levels.

9 Cost Projection

ComponentMonthly (ZAR)Notes
Cloudflare (Workers, D1, KV, Pages, AI Gateway)R0Free tier covers all
Workers AI (Llama + embeddings)~R90 – R180~$5-10/mo
Gemini API (Flash + Pro)~R180 – R540~$10-30/mo via AI Studio
Anthropic API (Claude Sonnet)~R360 – R720~$20-40/mo for quality tasks
Google WorkspaceExistingAlready provisioned
TotalR630 – R1,440~$35-80/mo

10 Decision Points for Next Session

Before wiring, decide:

  1. Deploy agilex-tools to agilex-tools.pages.dev?
  2. Create AI Gateway + set Gemini/Claude API keys?
  3. Start Huly locally for MCP testing?
  4. Google Workspace service account — create now or defer?

Quick wins (30 min total):

  1. npm run build && wrangler pages deploy on agilex-tools
  2. Set CV_PARSER_URL on portal
  3. Create AI Gateway in CF dashboard
  4. Set 3 secrets: CF_AIG_TOKEN, GOOGLE_AI_KEY, ANTHROPIC_API_KEY
  5. Deploy portal → real CV parse + real scoring live