feat: service agent recipe with dx pipeline

.github/workflows/ci-pr.yml

@@ -180,9 +180,9 @@ jobs:
             - name: 'Assign Manage Prompt Template permission set'
               run: sf org assign permset -n EinsteinGPTPromptTemplateManager
 
-            # Deploy source to scratch org
-            - name: 'Push source to scratch org'
-              run: sf project deploy start --dev-debug
+            # Deploy employee agent source to scratch org
+            - name: 'Deploy employee agent recipes'
+              run: sf project deploy start --source-dir force-app
 
             # Assign permission sets
             - name: 'Assign permission sets to default user'
@@ -194,6 +194,25 @@ jobs:
             - name: 'Import sample data'
               run: sf data tree import -p ./data/data-plan.json
 
+            # Create agent user for service agent deployment
+            - name: 'Create agent user for service agent'
+              id: service-agent-user
+              run: |
+                  agent_user=$(node scripts/setup-service-agent.js --target-org scratch-org)
+                  echo "username=$agent_user" >> "$GITHUB_OUTPUT"
+
+            # Assign base permission set to agent user
+            - name: 'Assign base permission set to agent user'
+              run: sf org assign permset -n Agent_Script_Recipes_Data --on-behalf-of "${{ steps.service-agent-user.outputs.username }}" -o scratch-org
+
+            # Deploy service agent source to scratch org
+            - name: 'Deploy service agent recipes'
+              run: sf project deploy start --source-dir force-app-service
+
+            # Assign service agent permission set (deployed with force-app-service)
+            - name: 'Assign service agent permission set to agent user'
+              run: sf org assign permset -n Customer_Service_Agent_Data --on-behalf-of "${{ steps.service-agent-user.outputs.username }}" -o scratch-org
+
             # Run Apex tests in scratch org
             - name: 'Run Apex tests'
               run: sf apex test run -c -r human -d ./tests/apex -w 20

.github/workflows/ci.yml

@@ -120,9 +120,9 @@ jobs:
             - name: 'Assign Manage Prompt Template permission set'
               run: sf org assign permset -n EinsteinGPTPromptTemplateManager
 
-            # Deploy source to scratch org
-            - name: 'Push source to scratch org'
-              run: sf project deploy start --dev-debug
+            # Deploy employee agent source to scratch org
+            - name: 'Deploy employee agent recipes'
+              run: sf project deploy start --source-dir force-app
 
             # Assign permission sets
             - name: 'Assign permission sets to default user'
@@ -134,6 +134,25 @@ jobs:
             - name: 'Import sample data'
               run: sf data tree import -p ./data/data-plan.json
 
+            # Create agent user for service agent deployment
+            - name: 'Create agent user for service agent'
+              id: service-agent-user
+              run: |
+                  agent_user=$(node scripts/setup-service-agent.js --target-org scratch-org)
+                  echo "username=$agent_user" >> "$GITHUB_OUTPUT"
+
+            # Assign base permission set to agent user
+            - name: 'Assign base permission set to agent user'
+              run: sf org assign permset -n Agent_Script_Recipes_Data --on-behalf-of "${{ steps.service-agent-user.outputs.username }}" -o scratch-org
+
+            # Deploy service agent source to scratch org
+            - name: 'Deploy service agent recipes'
+              run: sf project deploy start --source-dir force-app-service
+
+            # Assign service agent permission set (deployed with force-app-service)
+            - name: 'Assign service agent permission set to agent user'
+              run: sf org assign permset -n Customer_Service_Agent_Data --on-behalf-of "${{ steps.service-agent-user.outputs.username }}" -o scratch-org
+
             # Run Apex tests in scratch org
             - name: 'Run Apex tests'
               run: sf apex test run -c -r human -d ./tests/apex -w 20

.husky/pre-commit

@@ -1 +1,2 @@
+node scripts/clean-service-agent.js
 npm run precommit

AGENTS.md

@@ -16,6 +16,8 @@ Detailed rules and guidelines are in the `.airules/` directory. Read the relevan
 
 ## Project Layout
 
-- **Agent scripts:** `force-app/**/aiAuthoringBundles/**/*.agent`
-- **Apex services:** `force-app/**/classes/*.cls`
+- **Employee Agent scripts:** `force-app/**/aiAuthoringBundles/**/*.agent`
+- **Service Agent scripts:** `force-app-service/**/aiAuthoringBundles/**/*.agent`
+- **Apex services:** `force-app/**/classes/*.cls` and `force-app-service/**/classes/*.cls`
 - **Recipes:** each subdirectory under `force-app/main/` is a self-contained recipe
+- **Service Agent recipes:** `force-app-service/` contains service agent examples that require a `default_agent_user`

README.md

@@ -78,6 +78,39 @@ If you don't have an org yet, you can sign up for a free [Developer Edition Org]
     sf data import tree --plan data/data-plan.json
     ```
 
+1. **(Service Agent recipes)** Install npm dependencies. This is required for the setup script that creates and configures the agent user:
+
+    ```bash
+    npm install
+    ```
+
+1. **(Service Agent recipes)** Create the agent user and prepare the service agent metadata for deployment. Service Agents (unlike Employee Agents) require a `default_agent_user` — an org-specific user that the agent runs as. This script creates that user and injects it into all `.agent` files under `force-app-service/`:
+
+    ```bash
+    npm run setup:service-agent
+    ```
+
+    If deploying to a specific org (not your default), pass the target org alias:
+
+    ```bash
+    npm run setup:service-agent -- --target-org my-org-alias
+    ```
+
+1. **(Service Agent recipes)** Deploy the service agent metadata:
+
+    ```bash
+    sf project deploy start --source-dir force-app-service
+    ```
+
+1. **(Service Agent recipes)** Assign the required permission sets to the agent user so the service agent can access recipe data:
+
+    ```bash
+    sf org assign permset -n Agent_Script_Recipes_Data --on-behalf-of <agent-username>
+    sf org assign permset -n Customer_Service_Agent_Data --on-behalf-of <agent-username>
+    ```
+
+    Replace `<agent-username>` with the username printed by the `setup:service-agent` script in the previous step.
+
 1. Open your org with the **Agentforce Studio** app displayed:
 
     ```bash
@@ -87,7 +120,8 @@ If you don't have an org yet, you can sign up for a free [Developer Edition Org]
 > [!TIP]
 > **Agentforce Studio** can be reached from the App Launcher. From there, click **View All** then select the **Agentforce Studio** app.
 
-**Post installation:** when working with the recipes, assign the **Agent Script Recipes Data** permission set to your agent user to avoid access issues.
+> [!NOTE]
+> **What is a Service Agent?** Unlike Employee Agents (which run as the logged-in user), Service Agents are external-facing agents that run under a dedicated agent user. This user is org-specific, which is why the `npm run setup:service-agent` step is needed to dynamically create and configure it before deployment.
 
 ## Optional Installation Instructions
 

bin/install-scratch.bat

@@ -23,8 +23,8 @@ cmd.exe /c sf org assign permset -n EinsteinGPTPromptTemplateManager
 call :checkForError
 @echo:
 
-echo Pushing source...
-cmd.exe /c sf project deploy start
+echo Deploying employee agent recipes...
+cmd.exe /c sf project deploy start --source-dir force-app
 call :checkForError
 @echo:
 
@@ -36,11 +36,28 @@ cmd.exe /c sf org assign permset -n Agent_Script_Recipes_App
 call :checkForError
 @echo:
 
+echo Importing sample data...
+cmd.exe /c sf data tree import -p data/data-plan.json
 call :checkForError
 @echo:
 
-echo Importing sample data...
-cmd.exe /c sf data tree import -p data/data-plan.json
+echo Creating agent user for service agent...
+for /f "tokens=*" %%a in ('node scripts/setup-service-agent.js') do set AGENT_USER=%%a
+call :checkForError
+@echo:
+
+echo Assigning base permission set to agent user...
+cmd.exe /c sf org assign permset -n Agent_Script_Recipes_Data --on-behalf-of %AGENT_USER%
+call :checkForError
+@echo:
+
+echo Deploying service agent recipes...
+cmd.exe /c sf project deploy start --source-dir force-app-service
+call :checkForError
+@echo:
+
+echo Assigning service agent permission set...
+cmd.exe /c sf org assign permset -n Customer_Service_Agent_Data --on-behalf-of %AGENT_USER%
 call :checkForError
 @echo:
 

bin/install-scratch.sh

@@ -22,8 +22,8 @@ echo "Assigning Manage Prompt Templates permission set..."
 sf org assign permset -n EinsteinGPTPromptTemplateManager && \
 echo "" && \
 
-echo "Pushing source..." && \
-sf project deploy start && \
+echo "Deploying employee agent recipes..." && \
+sf project deploy start --source-dir force-app && \
 echo "" && \
 
 echo "Assigning Agent Script permission sets..." && \
@@ -35,6 +35,22 @@ echo "Importing sample data..." && \
 sf data import tree --plan data/data-plan.json && \
 echo "" && \
 
+echo "Creating agent user for service agent..." && \
+agent_user=$(node scripts/setup-service-agent.js) && \
+echo "" && \
+
+echo "Assigning base permission set to agent user..." && \
+sf org assign permset -n Agent_Script_Recipes_Data --on-behalf-of "$agent_user" && \
+echo "" && \
+
+echo "Deploying service agent recipes..." && \
+sf project deploy start --source-dir force-app-service && \
+echo "" && \
+
+echo "Assigning service agent permission set..." && \
+sf org assign permset -n Customer_Service_Agent_Data --on-behalf-of "$agent_user" && \
+echo "" && \
+
 echo "Opening org..." && \
 sf org open -p lightning/n/standard-AgentforceStudio && \
 echo ""

force-app-service/README.md

@@ -0,0 +1,22 @@
+# Service Agent Recipes
+
+This directory contains Agentforce **Service Agent** examples. Service Agents are external-facing agents that run under a dedicated agent user rather than the logged-in user.
+
+## Key Difference from Employee Agents
+
+Service Agents require a `default_agent_user` field in the agent config. This value is org-specific (it contains the org ID), so it cannot be committed to source control. Instead, a placeholder token (`__AGENT_USER_PLACEHOLDER__`) is used in the `.agent` files and replaced at deploy time.
+
+## Deployment
+
+See the root [README](../README.md#installing-the-app-using-a-developer-edition-org) for full deployment steps. The key additional steps for service agents are:
+
+1. `npm run setup:service-agent` — creates the agent user and replaces the placeholder
+2. `sf project deploy start --source-dir force-app-service` — deploys the service agent metadata
+
+A pre-commit hook automatically restores the placeholder before any commit so org-specific values are never pushed to the repository.
+
+## Recipes
+
+| Recipe                                        | Description                                                                                       |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| [CustomerServiceAgent](customerServiceAgent/) | Service agent that classifies issues, searches the knowledge base, and creates or escalates cases |