Agentforce Data-Aware Agent POC

An intelligent Salesforce agent that combines schema discovery, dynamic action routing, input validation, and knowledge-grounded responses for enterprise-grade AI automation.

🎯 Core Capabilities

Dynamic Schema Discovery

Auto-discovers org metadata (objects, fields, relationships)
FLS/sharing-aware data operations with governance
Portable across different Salesforce orgs

Intelligent Action Routing

Smart Goal Analysis: Automatically routes requests based on keywords
- "reserve inventory" → InventoryReserve action
- "update opportunity" → UpdateOpportunityStage action
Extensible Framework: Easy to add new routing rules

Checkpoint Guard System

Preflight Validation: Verifies all required inputs before database operations
Type Safety: Validates numeric fields, required vs optional fields
Error Prevention: Blocks invalid data from reaching the database
Clear Messaging: Provides specific error messages for validation failures

Knowledge-Grounded Responses

Data Library Integration: Uses Salesforce Knowledge for RAG
Fallback Mechanisms: Apex-based knowledge retrieval when Data Library unavailable
Citations & Attribution: Source tracking for grounded responses

🤖 Available Actions

The agent supports dynamic DOMAIN actions that are automatically routed based on user goals:

InventoryReserve (Primary Action)

Trigger: Goals containing "inventory", "stock", or "reserve"
Function: Creates high-priority Tasks to represent inventory reservations
Fields: Product2Id (required), Quantity (required, numeric > 0), AccountId (optional)
Validation: Checkpoint guard ensures all inputs are valid before database operations

UpdateOpportunityStage (Default Action)

Trigger: All other goals (default routing)
Function: Updates Opportunity stage with FLS/sharing compliance
Fields: Id (required), StageName (required)
Validation: Standard Salesforce validation + guardrails

📝 Structured Prompt Templates

The project includes reusable prompt templates for consistent agent behavior:

LeadQualification.prompt

Purpose: Intelligent lead qualification with dynamic schema discovery
Features: Picklist-aware status updates, task creation, FLS compliance
Use Case: Sales automation, lead scoring workflows

PersonalShoppingRecommendation.prompt

Purpose: E-commerce product recommendations with inventory awareness
Features: Price filtering, stock checking, knowledge-grounded suggestions
Use Case: Customer service, personalized shopping assistance

LoanEligibility.prompt

Purpose: Financial loan eligibility assessment with compliance
Features: PII protection, risk assessment, automated decision workflows
Use Case: Financial services, loan processing automation

InventoryCheck.prompt

Purpose: Real-time inventory verification and stock management
Features: Dynamic catalog checking, stock level monitoring, automated alerts
Use Case: E-commerce, supply chain management

Key Benefits:

🔍 Schema-Aware: No hard-coded field names or SOQL
🛡️ Governed: FLS and sharing rule compliance + checkpoint validation
📚 Knowledge-Integrated: Works with Data Libraries and Knowledge articles
🔄 Portable: Adapts to different org configurations
📋 Structured Output: JSON blueprints for safe, auditable operations
⚡ Intelligent Routing: Automatic action selection based on goal analysis

Complete Template Guide

🚀 Quick Start

Prerequisites

Salesforce CLI installed (sf)
Dev Hub access for scratch orgs
Git for version control

Development Setup

# Clone the repository
git clone https://github.com/dentity007/Agentforce-Data-Aware-Agent.git
cd agentforce-data-aware

# Authenticate with Dev Hub
sf org login web --alias devhub --set-default-dev-hub

# Create scratch org
sf org create scratch --definition-file config/project-scratch-def.json --alias agent-data-aware --set-default --duration-days 7 --wait 10

# Deploy and setup
sf project deploy start --ignore-conflicts --wait 30
sf org assign permset --name GenAIAgentPermission
sf org open

Test the Agent

Try these example goals to see intelligent routing in action:

"Reserve 5 units of inventory for product ABC123"
→ Automatically routes to InventoryReserve action
→ Validates Quantity > 0, creates Task

"Update the opportunity stage to Closed Won"
→ Routes to UpdateOpportunityStage action
→ Updates Opportunity with governance

Development Tools

This project includes a scaffolding script for common development tasks:

# Make the script executable (one-time setup)
chmod +x scripts/scaffold.sh

# Setup development environment
./scripts/scaffold.sh setup dev

# Create new components
./scripts/scaffold.sh create class MyNewClass
./scripts/scaffold.sh create trigger MyTrigger Account
./scripts/scaffold.sh create lwc myComponent

# Deploy and test
./scripts/scaffold.sh deploy
./scripts/scaffold.sh test

# Authenticate
sf org login web --alias devhub --set-default-dev-hub

# Create scratch org
sf org create scratch --definition-file config/project-scratch-def.json --alias agent-data-aware --set-default --duration-days 7 --wait 10

# Deploy and setup
sf project deploy start --ignore-conflicts --wait 30
sf org assign permset --name GenAIAgentPermission
sf org open

# Test intelligent routing
# "Reserve 5 units of inventory for product ABC" → InventoryReserve action
# "Update opportunity stage to Closed Won" → UpdateOpportunityStage action

🧪 Comprehensive Testing

This project maintains 100% test pass rate with comprehensive coverage across all components:

# Run all tests (40+ Apex classes, 8 dedicated test suites)
sf apex run test --result-format human --code-coverage --wait 30

# Run specific test suites
sf apex run test --tests InventoryReserveTests --result-format human --wait 10
sf apex run test --tests PlannerRouteTests --result-format human --wait 10
sf apex run test --tests OrchestratorCheckpointGuardTests --result-format human --wait 10
sf apex run test --tests AgentLeadActionTests,AgentQueryTests,AgentSchemaTests --result-format human --wait 10

# Run with coverage requirements
sf apex run test --result-format human --code-coverage --coverage-threshold 75 --wait 30

Test Coverage Breakdown:

Core Functionality Tests (100% pass rate)

InventoryReserveTests (3 tests): Task creation, input validation, optional fields
PlannerRouteTests (2 tests): Intelligent routing for inventory vs opportunity goals
OrchestratorCheckpointGuardTests (3 tests): Input validation before database operations

Integration Tests

AgentLeadActionTests: Lead qualification workflows
AgentQueryTests: Safe SOQL execution with FLS/sharing
AgentSchemaTests: Dynamic schema discovery
MetadataDiscoveryTests: Object/field metadata operations
PlannerAndOrchestratorTests: End-to-end orchestration
PrivacyGuardTests: PII redaction and data protection
SchemaSlicerTests: Metadata slicing and filtering

Validation Features

✅ Checkpoint Guards: Input validation prevents invalid database operations
✅ FLS Compliance: All operations respect field-level security
✅ Sharing Rules: Data access follows org sharing configuration
✅ Error Handling: Comprehensive error messages and graceful failures

Core Apex Classes (40+ Classes)

Intelligent Routing: Planner (goal analysis), ActionOrchestrator (checkpoint guards)
Schema Discovery: MetadataDiscovery, SchemaSlicer, OrgSchemaBootstrap
Data Operations: SOQLBuilder, SafeQueryApex, DataCloudQueryApex
Security & Governance: FLS, PrivacyGuard, JSONUtil
DOMAIN Actions: InvocableActionFactory, DomainActionRegistry
Business Logic: LeadQualificationAction, LeadScoreService, FollowUpApex
Knowledge Integration: KnowledgeRetrieverApex (RAG fallback)
Testing: Comprehensive test suite with 8 test classes (100% pass rate)

GenAI Functions (11 Functions)

Data Operations: ExecuteSOQL, FindFields, FindObjects, FindRelationshipPath
AI Actions: QueryDataCloud, RunFlow, TriggerFollowUpAction, UpdateLeadStatusAction
Business Logic: CheckInventoryAction, DiscoverMetadataAction, RetrieveKnowledgeSnippets

Prompt Templates (5 Templates)

LeadQualification: Sales automation with schema awareness
PersonalShoppingRecommendation: E-commerce with inventory checking
LoanEligibility: Financial services with PII protection
InventoryCheck: Supply chain management
DataAwarePrompt: General-purpose data operations

📚 Documentation

Project Overview

Master Roadmap: Complete project summary, architecture, and roadmap
One-Pager: Executive summary of capabilities and value proposition
LLM I/O Contract: Technical specification for AI model interfaces