# Sf Agentforce

> |

- **Type:** Skill
- **Install:** `agentstack add skill-clientell-ai-salesforce-skills-sf-agentforce`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Clientell-Ai](https://agentstack.voostack.com/s/clientell-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Clientell-Ai](https://github.com/Clientell-Ai)
- **Source:** https://github.com/Clientell-Ai/salesforce-skills/tree/main/skills/sf-agentforce

## Install

```sh
agentstack add skill-clientell-ai-salesforce-skills-sf-agentforce
```

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

## About

# Agentforce Development Guide

You are a Salesforce Agentforce specialist. Build production-ready autonomous and deterministic agents following Salesforce best practices. API version 66.0 for all Agentforce features.

## Agent Setup

### Creating an Agent

Agents are created in **Setup > Agentforce > Agents** or via metadata deployment.

Two agent types:

| Agent Type | API Name | Use Case |
|---|---|---|
| Service Agent | `AgentforceServiceAgent` | Customer-facing, runs as Agent User, deployed to channels |
| Employee Agent | `AgentforceEmployeeAgent` | Internal-facing, runs as logged-in user, embedded in apps |

### Agent User Configuration (Service Agents Only)

Service Agents require a dedicated **Einstein Agent User**:
1. Create a user with the `Salesforce Integration` license
2. Assign the `AgentforceServiceAgent` permission set
3. Grant object/field permissions the agent needs via permission sets
4. Set as `default_agent_user` in agent configuration

Employee Agents run as the logged-in user and do not need a dedicated agent user.

### Channel Configuration

Agents can be deployed to:
- **Messaging channels** (web chat, SMS, WhatsApp)
- **Embedded Service deployments** (Lightning Web Runtime)
- **Slack** (Employee Agent)
- **API** (Agent Runtime API for programmatic access)

Configure channels in **Setup > Messaging Settings** or **Embedded Service Deployments**.

---

## Topics

Topics define the scope of what an agent can handle. Each topic is a logical domain with its own instructions, actions, and scope boundaries.

### Topic Design Principles

- **Specific scope**: Each topic should have a clear, non-overlapping domain
- **Natural language description**: The description is the routing signal — the planner uses it to match user utterances
- **Focused instructions**: Tell the agent how to behave within this topic
- **Bounded actions**: Only attach actions relevant to the topic

### Topic Structure

A topic consists of:
- **Label and API Name**: Human-readable name and developer reference
- **Description**: Natural language explanation of what this topic covers (this drives routing)
- **Scope**: Define what is in-scope and out-of-scope explicitly
- **Instructions**: Step-by-step guidance for agent behavior within this topic
- **Actions**: The tools available to the agent when this topic is active

### Topic Routing

The planner matches user utterances to topics based on:
1. Topic description similarity to the utterance
2. Scope definitions (in-scope vs out-of-scope)
3. Instruction context

**Avoid scope overlap** between sibling topics. If two topics could match the same utterance, the planner may misroute. Use explicit scope boundaries:

```text
In scope: Order status inquiries, order tracking, delivery estimates
Out of scope: Order creation, order cancellation (handled by Order Management topic)
```

---

## Agent Actions

Actions are the tools an agent can invoke. Each action wraps a target implementation.

### Action Types

| Action Type | Target | Best For | Registered Via |
|---|---|---|---|
| Flow Action | Screen Flow or Autolaunched Flow | Declarative logic, guided interactions, multi-step processes | `GenAiFunction` |
| Apex Action | `@InvocableMethod` class | Complex business logic, callouts, calculations | `GenAiFunction` |
| PromptTemplate Action | PromptTemplate metadata | Generated text, summaries, recommendations, drafts | `GenAiFunction` |
| External Service Action | External Service registration | Third-party API calls via OpenAPI spec | `GenAiFunction` |

### When to Use Each

- **Flow**: Default choice. Safest, most maintainable, supports guided user interaction
- **Apex**: When you need complex logic, external callouts, or custom data processing
- **PromptTemplate**: When the output is generated text (summaries, emails, recommendations)
- **External Service**: When calling external APIs registered via External Services

### Action Configuration

Every action requires:
- **Capability description**: Natural language explaining when the agent should invoke this action
- **Input parameters**: Mapped from conversation context or user input
- **Output parameters**: Returned to the agent for response generation

Input/output parameter names must match the target contract exactly:
- For Flows: match Flow input/output variable API names
- For Apex: match `@InvocableVariable` field names
- For PromptTemplates: match template input/output variable names

### Action Grouping with GenAiPlugin

Group related `GenAiFunction` entries into a `GenAiPlugin` for logical organization. A plugin represents a capability domain (e.g., "Order Management" containing lookup, status, and cancel actions).

---

## PromptTemplate

PromptTemplate metadata defines reusable prompt configurations for agent grounding, text generation, and structured responses.

### Template Types

| Type | Use Case |
|---|---|
| `einstein_gpt__fieldCompletion` | Single-field generation |
| `einstein_gpt__salesEmail` | Email drafting |
| `einstein_gpt__flex` | General-purpose flex templates |
| `einstein_gpt__chat` | Conversational agent grounding |

### Template Components

- **Input variables**: Data passed into the template (record fields, user input, context)
- **Output variable**: The generated result
- **Resolution steps**: Ordered prompt fragments, grounding data, and instructions
- **Model configuration**: Which model to use and parameters

### PromptTemplate as Agent Action

When used as an agent action:
1. Create the PromptTemplate metadata
2. **Activate the template** (Draft templates cause publish errors)
3. Register it as a `GenAiFunction`
4. Attach to a topic
5. Map inputs from conversation context

### Models API Integration

Use the Models API from Apex for custom model routing beyond PromptTemplates:

```apex
public with sharing class ModelService {
    @InvocableMethod(label='Generate Summary')
    public static List generateSummary(List inputs) {
        ConnectApi.EinsteinLlmGenerateParams params =
            new ConnectApi.EinsteinLlmGenerateParams();
        params.promptTextorId = 'Summarize: ' + inputs[0];
        ConnectApi.EinsteinLlmGenerationOutput output =
            ConnectApi.EinsteinAI.generateMessages(params);
        return new List{ output.generatedMessages[0].text };
    }
}
```

---

## Agent Scripts (Deterministic Agents)

Agent Scripts provide a **code-first, FSM-based** approach for building deterministic agents. Use `.agent` files with a declarative DSL.

### When to Use Agent Scripts vs Setup UI

| Criteria | Agent Script | Setup UI / Agent Builder |
|---|---|---|
| Routing control | Deterministic (state machine) | LLM-directed (planner) |
| Version control | `.agent` files in source | Metadata XML retrieved from org |
| Repeatability | Identical behavior every time | May vary with planner interpretation |
| Complexity ceiling | High (FSM + guards + transitions) | Moderate (topic + actions) |
| Best for | Strict compliance flows, regulated processes | General customer service, flexible Q&A |

### Agent Script DSL Structure

```yaml
config:
  developer_name: MyServiceAgent
  master_label: My Service Agent
  agent_description: Handles customer service inquiries
  agent_type: AgentforceServiceAgent
  default_agent_user: einstein_agent_user@company.com

variables:
  caseNumber:
    type: string
    description: The case number provided by the customer
  customerVerified:
    type: boolean
    description: Whether the customer has been verified
    default: False

system:
  greeting: Hello! I am your service agent. How can I help you today?

start_agent:
  topic: Greeting

topic: Greeting
  description: Initial greeting and intent identification
  instructions: ->
    Greet the customer and ask how you can help.
    Identify their intent and route to the appropriate topic.
  actions:
    identifyIntent:
      target: flow://Identify_Customer_Intent
      inputs:
        utterance: $input
      outputs:
        detectedIntent: intent
  transitions:
    - when: detectedIntent == "case_status"
      go_to: CaseStatus
    - when: detectedIntent == "new_case"
      go_to: NewCase
```

### Key DSL Rules

1. **Exactly one `start_agent` block** per file
2. **No mixed tabs and spaces** — pick one and be consistent
3. **Booleans**: `True` / `False` (capitalized)
4. **No `else if`** — use separate conditions or transitions
5. **No nested `if` blocks**
6. **`linked` variables** cannot have defaults and cannot use `object`/`list` types
7. **Actions use `@actions.` prefix** when referenced in instructions
8. **`run @actions.X`** only for topic-level actions with a `target:` definition

### Agent Script CLI

```bash
# Validate an agent script
sf agent validate authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Publish an agent script
sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Activate the agent
sf agent activate --api-name MyAgent -o TARGET_ORG
```

Publishing does **not** activate — always run `sf agent activate` separately.

---

## Metadata Structure

Key metadata types for Agentforce:

| Metadata Type | File Suffix | Purpose |
|---|---|---|
| Bot | `.agent-meta.xml` | Agent definition, versions, context variables |
| GenAiTopic | `.agentTopic-meta.xml` | Topic with description, scope, instructions, actions |
| GenAiFunction | `.genAiFunction-meta.xml` | Single action wrapping a Flow, Apex, or PromptTemplate target |
| GenAiPlugin | `.genAiPlugin-meta.xml` | Logical grouping of related GenAiFunctions |
| PromptTemplate | `.promptTemplate-meta.xml` | Prompt configuration with inputs, outputs, and model settings |

Each GenAiFunction must specify:
- `targetType` (Flow, Apex, PromptTemplate, ExternalService)
- `targetName` (API name of the target)
- `capabilityDescription` (when the agent should use this action)
- `inputs` and `outputs` with names matching the target contract exactly

Full XML templates for all metadata types: [references/agentforce-reference.md](references/agentforce-reference.md)

---

## Testing Agents

### Agentforce Testing Center

The Testing Center (Setup > Agentforce > Testing Center) provides UI-based testing with multi-turn conversation validation.

### CLI Testing Commands

```bash
sf agent test run --api-name MyAgent -o TARGET_ORG --json
sf agent test run --spec-file tests/order-status.yaml -o TARGET_ORG --json
sf agent test results --test-run-id 0Atxx0000000001 -o TARGET_ORG --json
```

Test spec YAML format and multi-turn examples: [references/agentforce-reference.md](references/agentforce-reference.md)

### Test Coverage Categories

Ensure tests cover:
1. **Topic routing**: Correct topic matched for each utterance
2. **Action invocation**: Expected actions called with correct parameters
3. **Context preservation**: Multi-turn conversations maintain state
4. **Guardrails**: Off-topic, harmful, or out-of-scope inputs handled
5. **Escalation**: Agent escalates to human when appropriate
6. **Phrasing variation**: Multiple ways of asking the same question

### Test-Fix Loop

1. Run tests and capture failures
2. Classify failures (topic mismatch, action failure, context loss, guardrail failure)
3. Fix the agent (topic descriptions, action configs, instructions)
4. Re-publish and re-activate
5. Re-run focused tests before full regression

---

## Agent Observability

Monitor agent behavior in production using the Session Tracing Data Model (STDM) and EventLogFile.

### Session Tracing Data Model (STDM)

STDM captures structured telemetry for every agent session: sessions, interactions (turns), interaction steps, moments, and messages. Enable tracing in **Setup > Einstein AI > Session Tracing**. Data flows into Data Cloud for analysis.

Key STDM entities: `Session`, `Interaction`, `InteractionStep`, `Moment`, `Message`. Each interaction maps to a single user turn and the agent's response chain (topic match, action invocations, LLM calls).

### Session Transcripts

Query session transcripts via the Agent Runtime API or Data Cloud. Use transcripts to debug topic routing failures, inspect action parameters, and verify context preservation across turns.

### EventLogFile for Agent Events

`EventLogFile` captures agent-related platform events. Query with:
```soql
SELECT Id, EventType, LogDate, LogFileLength
FROM EventLogFile
WHERE EventType IN ('AIInteraction', 'AIInsightAction')
ORDER BY LogDate DESC
```

Use EventLogFile data for aggregate monitoring: invocation counts, error rates, and latency trends.

---

## Agent Persona Design

Design a consistent agent personality by defining voice attributes and encoding them into agent configuration.

### Voice Attributes

Define: **register** (formal to casual), **warmth** (neutral to empathetic), **brevity** (concise to detailed), **humor** (none to light). Align these with brand guidelines and audience expectations.

### System Instructions for Persona

Encode persona in the agent's system instructions or topic-level instructions. Include: identity statement, tone directives, a phrase book (preferred phrases), and a never-say list (banned phrases or topics). Keep instructions specific and testable.

### Guardrails for Persona

Define tone boundaries: how the agent adjusts tone for frustrated users vs happy-path conversations. Set hard limits (never use slang, never promise timelines) and soft guidelines (prefer active voice, use customer's name).

---

## GenAI Models API

The Models API provides programmatic access to LLMs through Apex via `ConnectApi.EinsteinAI.generateMessages()`. All calls are automatically protected by the Einstein Trust Layer (prompt defense, toxicity detection, PII masking, audit trail, data grounding, zero data retention).

Configure model routing in **Setup > Einstein AI > Model Management**. Override at the PromptTemplate level for per-template model selection.

See [references/agentforce-reference.md](references/agentforce-reference.md) for Apex usage examples and Trust Layer details.

---

## Gotchas

### Agent User License
Service Agents require an Einstein Agent User license. Without it, publish succeeds but the agent cannot execute actions at runtime. Verify the user has `AgentforceServiceAgent` permission set.

### Topic Scope Overlap
Overlapping topic descriptions cause routing ambiguity. The planner may match the wrong topic or oscillate between topics. Fix by making scope boundaries explicit and non-overlapping.

### Action Parameter Mapping
Input/output parameter names in `GenAiFunction` must exactly match the target contract. Mismatched names cause silent failures where the action is invoked but receives null inputs.

### PromptTemplate Draft Status
A PromptTemplate in Draft status causes `invalid input/output parameters` errors during agent publish. Always activate templates before publishing the agent.

### API Version Requirement
Agentforce features require API version **66.0 or higher**. Metadata deployed at lower API versions will be rejected or ignored.

### Publish vs Activate
Publishing an agent does not activate it. After `sf agent publish`, you must separately run `sf agent activate`. Forgetting this step means the agent is deployed but unreachable.

### Agent Script Syntax Pitfalls
- `else if` is not supported — use separate conditions
- Nested `if` blocks are not allowed
- `linked` variables cannot have default values
- Booleans must be `True`/`False` (case-sensitive)
- Top-level `actions:` block is invalid — actions belong inside topics

### Deploy Order Matters
Supporting metadata must be deployed before the agent:
1. Custom objects/fields
2. Apex classes (InvocableMethod)
3. Flows
4. PromptTemplates (and activate them)
5. GenAiFunction / GenAiPlugin
6. Agent metadata
7. Publish, then activate

### Test Coverage
While there is no enforced minimum test percentage for agents (unlike Apex), untested agents are risky. Cover at minimum: each topic, each action, off-topic handling, and escalation paths.

---

## Workflow

### Step-by-Step

…

## Source & license

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

- **Author:** [Clientell-Ai](https://github.com/Clientell-Ai)
- **Source:** [Clientell-Ai/salesforce-skills](https://github.com/Clientell-Ai/salesforce-skills)
- **License:** Apache-2.0

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-clientell-ai-salesforce-skills-sf-agentforce
- Seller: https://agentstack.voostack.com/s/clientell-ai
- 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%.