# Sf Agentforce Development

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-jiten-singh-shahi-salesforce-claude-code-sf-agentforce-development`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jiten-singh-shahi](https://agentstack.voostack.com/s/jiten-singh-shahi)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jiten-singh-shahi](https://github.com/jiten-singh-shahi)
- **Source:** https://github.com/jiten-singh-shahi/salesforce-claude-code/tree/main/.cursor/skills/sf-agentforce-development
- **Website:** https://www.npmjs.com/package/scc-universal

## Install

```sh
agentstack add skill-jiten-singh-shahi-salesforce-claude-code-sf-agentforce-development
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Agentforce Development

Procedures for building Agentforce AI agents. Architecture, syntax reference, metadata types, instruction guidelines, and context engineering principles live in the reference file.

@../_reference/AGENTFORCE_PATTERNS.md

## When to Use

- Building Agentforce AI agents with Agent Script (`.agent` files)
- Generating and publishing authoring bundles via CLI
- Configuring agent topics, actions, or conversation instructions
- Creating custom Apex actions or Flow actions for Agentforce
- Testing agents with YAML test specs, CLI, or Testing Center
- Deploying agent metadata (GenAi types) to orgs

---

## Agent Types

| Type | Audience | Channel | Use Case |
|------|----------|---------|----------|
| Einstein Copilot | Internal users | Salesforce UI sidebar | Sales/service rep productivity |
| Experience Cloud Agent | External users | Messaging, web chat | Customer self-service |
| Custom Agent | Any | API, custom channel | Bespoke workflows, backend automation |

---

## Development Approaches

| | Agent Script (Recommended) | Classic Setup |
|---|---|---|
| **API version** | v65+ | v60+ |
| **Surface** | `.agent` files in VS Code + CLI | Agentforce Builder UI |
| **Source control** | Yes — diffable `.agent` files | No — UI-only |
| **CI/CD** | Full: validate → publish → test → activate | Limited: deploy GenAi metadata |
| **When to use** | All new agents; teams needing code review | Orgs on API 
         | Analyze the message and determine the best topic.
      actions:
         verify: @utils.transition to @topic.identity
            description: "Verify customer identity"
         orders: @utils.transition to @topic.order_management
            description: "Help with order status or modifications"
         escalate: @utils.escalate
            description: "Transfer to human agent"

topic identity:
   label: "Identity Verification"
   description: "Verifies customer identity via email lookup"

   actions:
      lookup_customer:
         description: "Look up customer by email"
         inputs:
            email: string
               description: "Customer email address"
               is_required: True
         outputs:
            found: boolean
               description: "Whether a matching customer was found"
               is_used_by_planner: True
         target: "apex://LookupCustomerAction"

   reasoning:
      instructions: ->
         if @variables.is_verified == True:
            | Customer is already verified.
            transition to @topic.order_management
         | Ask for their email address to verify identity.
      actions:
         lookup: @actions.lookup_customer
            with email = ...
            set @variables.is_verified = @outputs.found

   after_reasoning: ->
      if @variables.is_verified == True:
         transition to @topic.order_management

topic order_management:
   label: "Order Management"
   description: "Helps customers check order status"

   actions:
      get_order_details:
         description: "Retrieve order details by order number"
         inputs:
            order_number: string
               description: "The order number to look up"
               is_required: True
               is_user_input: True
            customer_email: string
               description: "Customer email for verification"
               is_required: True
         outputs:
            status: string
               description: "Current order status"
               is_displayable: True
               is_used_by_planner: True
            tracking_number: string
               description: "Shipping tracking number"
               is_displayable: True
         target: "apex://GetOrderDetailsAction"

   reasoning:
      instructions: ->
         if @variables.is_verified == False:
            transition to @topic.identity
         | Help the customer with their order inquiry.
      actions:
         get_order: @actions.get_order_details
            with order_number = ...
            with customer_email = @variables.customer_email
```

> **Two-block pattern**: Actions are declared in a top-level `actions:` block (with `target`, `inputs`, `outputs`) and referenced in `reasoning.actions` via `@actions.` with `with`/`set`. The `target:` field resolves to the underlying implementation. In namespaced orgs, prefix: `target: "apex://ns__ClassName"` (check `sfdx-project.json`).

### Key Patterns

**Deterministic** (`->`) — guaranteed execution:

```
-> if @variables.is_verified == False:
     transition to @topic.identity
```

**LLM prompts** (`|`) — accumulated and sent to model:

```
| Help the customer with their order.
| Be concise and provide the order number.
```

**Deterministic action** (`run`) — bypasses LLM:

```
-> run @actions.get_recent_orders
      with customer_id = @variables.customer_id
      set @variables.recent_orders = @outputs.orders
```

---

## Action Types

### Apex @InvocableMethod

Apex actions are built by `sf-apex-agent` using patterns from `sf-apex-constraints`. Key Agentforce-specific requirements:

- **Labels/descriptions are critical** — the LLM reads these to decide routing
- **InvocableVariable descriptions** must specify data type and format: `"accountId — 18-digit Account record ID"`
- **Return result objects** (not void) — agent needs structured confirmation
- **Use `Database` class** (partial success) not DML verbs (all-or-nothing)
- **Varied verb names**: "Locate", "Retrieve", "Calculate" — not "Get X", "Get Y"
- **Decompose** complex actions to avoid CPU timeout (10s sync limit)
- **Long-running work**: enqueue Queueable, return requestId

### Other Action Types

MCP Server, Named Query, AuraEnabled, Apex Citations, Lightning Types, Adaptive Response Formats, Flow Actions, and Prompt Templates are documented in:

@_reference/ACTION_TYPES.md

For MCP Server actions specifically, see skill `sf-agentforce-mcp-actions`.

---

## Testing

Apex unit tests for `@InvocableMethod` actions are handled by `sf-apex-agent` using `sf-testing-constraints`. This section covers **agent-level testing** — verifying topic routing, action execution, and response quality.

### Agent Test Spec (YAML)

```yaml
name: Service_Agent_Tests
description: End-to-end tests for Customer Service Agent
subjectType: AGENT
subjectName: Service_Agent
subjectVersion: v1
testCases:
  - utterance: "What's the status of order #12345?"
    expectedTopic: Order_Management
    expectedActions:
      - get_order_details
    expectedOutcome: "Agent provides order status details including shipping info"
    contextVariables:
      - name: EndUserLanguage
        value: en
    metrics:
      - topic_sequence_match
      - action_sequence_match
      - bot_response_rating
      - coherence
      - completeness
      - conciseness
      - latency

  - utterance: "I need to file a complaint about my delivery"
    expectedTopic: Case_Management
    expectedActions:
      - create_support_case
    expectedOutcome: "Agent creates a case and provides the case number"
    metrics:
      - topic_sequence_match
      - action_sequence_match
      - bot_response_rating
      - instructionAdherence

  - utterance: "Hola, necesito ayuda con mi pedido"
    expectedTopic: Order_Management
    contextVariables:
      - name: EndUserLanguage
        value: es
    metrics:
      - topic_sequence_match
      - coherence
```

### Multi-Turn Conversation Testing

```yaml
testCases:
  - utterance: "I want to return my order"
    expectedTopic: Order_Management
    conversationHistory:
      - role: user
        message: "Hi, I need help"
      - role: agent
        message: "Hello! How can I help you today?"
        topic: topic_selector
      - role: user
        message: "I have a problem with order #12345"
      - role: agent
        message: "I found order #12345. It was delivered on March 15."
        topic: Order_Management
    metrics:
      - topic_sequence_match
      - action_sequence_match
```

### Custom Evaluations

```yaml
testCases:
  - utterance: "What's the weather in SF?"
    customEvaluations:
      - label: Temperature Check
        jsonPathExpression: $.actions[0].result.temperature
        comparisonOperator: greaterThan
        expectedValue: "0"
```

### CLI Test Workflow

```bash
# Generate test spec from agent definition
sf agent generate test-spec --output-file specs/testSpec.yaml

# Create test in org from YAML spec
sf agent test create --spec specs/testSpec.yaml --target-org MySandbox

# Run tests synchronously with JUnit output (CI-friendly)
sf agent test run --api-name Service_Agent_Tests --wait 10 \
    --result-format junit --output-dir ./test-results \
    --target-org MySandbox

# View results
sf agent test results --test-id  --target-org MySandbox

# List all agent tests
sf agent test list --target-org MySandbox
```

### Testing Tools Summary

| Tool | Purpose |
|---|---|
| **Agent Builder Preview** | Real-time conversational testing (simulated or live mode) |
| **Agentforce Testing Center** | Bulk test execution; auto-generates test cases from knowledge |
| **CLI (`sf agent test`)** | Headless testing, JUnit output, CI pipeline integration |
| **VS Code Agent Panel** | View/run tests + Agent Preview pane + Apex Replay Debugger |
| **Testing REST API** | Programmatic test execution from external CI systems |
| **Agent Grid (Beta)** | Spreadsheet-like rapid testing with real CRM data |

---

## Metadata & Deployment

```
force-app/main/default/
  aiAuthoringBundles/My_Agent/   # .agent + .bundle-meta.xml
  bots/My_Agent/                 # .bot-meta.xml
  botVersions/My_Agent.v1/      # .botVersion-meta.xml
  genAiPlannerBundles/My_Agent/  # .genAiPlannerBundle-meta.xml (auto-generated by publish)
  genAiPlugins/Topic_Name/       # .genAiPlugin-meta.xml
  genAiFunctions/Action_Name/    # .genAiFunction-meta.xml (Classic UI only — Agent Script wires via target:)
  aiEvaluationDefinitions/       # .aiEvaluationDefinition-meta.xml
```

**Deploy order (Classic UI)**: Bot/BotVersion → GenAiPromptTemplate → GenAiFunction → GenAiPlugin → GenAiPlannerBundle → AiAuthoringBundle → AiEvaluationDefinition → Activate

**Deploy order (Agent Script)**: Deploy Apex `@InvocableMethod` classes → `sf agent publish authoring-bundle` (handles everything else)

**Retrieve**: `sf project retrieve start --metadata "AiAuthoringBundle:My_Agent*"`

---

## Security

- Always use `with sharing` and `AccessLevel.USER_MODE` / `WITH USER_MODE`
- Ground Prompt Templates only with fields the user's profile can read
- Review agent conversations in Setup > Agent Conversations

---

## Classic Topics (Pre-Agent Script)

For orgs on API < v65, configure topics in Agentforce Builder UI with classification description, WILL/WILL NOT scope, and numbered instructions (positive framing). All instruction guidelines and context engineering principles from the reference apply identically.

---

## Related

- Agent: `sf-agentforce-agent` — for interactive guidance
- Constraints: sf-apex-constraints
- Reference: @../_reference/AGENTFORCE_PATTERNS.md

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jiten-singh-shahi](https://github.com/jiten-singh-shahi)
- **Source:** [jiten-singh-shahi/salesforce-claude-code](https://github.com/jiten-singh-shahi/salesforce-claude-code)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/scc-universal

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jiten-singh-shahi-salesforce-claude-code-sf-agentforce-development
- Seller: https://agentstack.voostack.com/s/jiten-singh-shahi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.